@xpufx/paseo-x-comms 0.3.0

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

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

@@ -0,0 +1,184 @@
+/**
+ * Text-run splitting for search highlighting, shared by every helper surface
+ * that paints matched query text and by the forges search surfaces that scroll
+ * to a match. A query is matched literally via `indexOf` on lowercased strings —
+ * never compiled as a regular expression — so user input cannot inject a
+ * pattern.
+ *
+ * Remote forge search is fuzzy: a returned issue may match a query it does not
+ * contain verbatim. When the literal query is absent the splitter highlights
+ * the query's multi-character tokens at word starts, so a fuzzy result still
+ * reads. Callers on a single primary label may additionally opt into marking
+ * the whole field when not even a token hits (`fallbackToWholeField`); callers
+ * that paint many small runs leave it off. `hasFuzzyHighlight` is the
+ * whole-surface test for go-to-match.
+ *
+ * `normalizeSearchQuery` strips surrounding quotes and whitespace for the local
+ * filter/highlight paths; remote search keeps the raw query.
+ */
+
+export interface HighlightPart {
+  /** The run's source text, in its original casing. */
+  text: string;
+  /** True when this run is an occurrence of the (normalized) query. */
+  matched: boolean;
+}
+
+const TOKEN_PATTERN = /[^\p{L}\p{N}]+/u;
+
+/**
+ * Normalize a search query for local matching and highlighting: trim, then peel
+ * any surrounding pair of matching single/double quotes (`"meta"`, `'meta'`,
+ * `""meta""`). Remote forge search keeps the raw query — Forgejo treats quotes
+ * as a phrase operator — so only the local paths normalize, letting quoted and
+ * unquoted input filter and paint identically. A lone quote is left intact.
+ */
+export function normalizeSearchQuery(query: string): string {
+  let value = query.trim();
+  while (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first !== '"' && first !== "'") || first !== last) break;
+    value = value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+export interface HighlightOptions {
+  /**
+   * When true and neither a literal nor a token hit exists, the whole text is
+   * returned as a single matched run so a fuzzy search result is still visibly
+   * marked. Off by default: callers that paint many small runs (label chips,
+   * markdown spans) must not light every one of them up.
+   */
+  fallbackToWholeField?: boolean;
+}
+
+/**
+ * Query pieces used for the token fallback. A query with no literal hit is
+ * split on non-alphanumeric boundaries; single-character tokens are dropped so
+ * a fuzzy query cannot paint a stray letter in every result.
+ */
+function queryTokens(needle: string): string[] {
+  return needle.split(TOKEN_PATTERN).filter((token) => token.length >= 2);
+}
+
+/** True when `index` begins a word (a word-start query token may prefix it). */
+function isWordStartAt(haystack: string, index: number): boolean {
+  return index === 0 || TOKEN_PATTERN.test(haystack[index - 1]);
+}
+
+/** Earliest word-start occurrence of `token` in `haystack` at or after `from`. */
+function firstTokenStart(haystack: string, token: string, from: number): number {
+  let index = haystack.indexOf(token, from);
+  while (index !== -1) {
+    if (isWordStartAt(haystack, index)) return index;
+    index = haystack.indexOf(token, index + 1);
+  }
+  return -1;
+}
+
+/**
+ * Split `text` into alternating unmatched/matched runs for every
+ * case-insensitive occurrence of `query`. Surrounding whitespace and matching
+ * surrounding quotes on the query are ignored; an empty or whitespace-only
+ * query (or empty text) yields the whole text as a single unmatched run.
+ *
+ * When the literal query is absent the splitter highlights the query's
+ * multi-character tokens at word starts. If no token hits either, the text is
+ * left unmatched unless the caller opted into `fallbackToWholeField`, which
+ * marks the whole field so a fuzzy result is never silently unmarked.
+ */
+export function splitHighlightParts(
+  text: string,
+  query: string,
+  options: HighlightOptions = {},
+): HighlightPart[] {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  if (!needle || !text) return [{ text, matched: false }];
+  const haystack = text.toLowerCase();
+  if (haystack.includes(needle)) return splitLiteralParts(text, haystack, needle);
+  const tokens = queryTokens(needle);
+  const tokenParts = tokens.length ? splitTokenParts(text, haystack, tokens) : null;
+  if (tokenParts) return tokenParts;
+  // Whole-field fallback: a fuzzy result may match on text the query never
+  // contains, so paint the field rather than leave the row unmarked.
+  return options.fallbackToWholeField ? [{ text, matched: true }] : [{ text, matched: false }];
+}
+
+/** Runs for every non-overlapping literal occurrence of `needle`. */
+function splitLiteralParts(text: string, haystack: string, needle: string): HighlightPart[] {
+  const parts: HighlightPart[] = [];
+  let cursor = 0;
+  while (cursor < text.length) {
+    const hit = haystack.indexOf(needle, cursor);
+    if (hit === -1) {
+      parts.push({ text: text.slice(cursor), matched: false });
+      break;
+    }
+    if (hit > cursor) parts.push({ text: text.slice(cursor, hit), matched: false });
+    parts.push({ text: text.slice(hit, hit + needle.length), matched: true });
+    cursor = hit + needle.length;
+  }
+  return parts.length > 0 ? parts : [{ text, matched: false }];
+}
+
+/**
+ * Runs matching any `token` beginning at a word boundary, so a fuzzy query
+ * paints the token that prefixes a word (`meta` inside `metadata`) and never a
+ * fragment mid-word (`eta` inside `metadata`). The longest token wins a shared
+ * start; ties fall to the earliest occurrence. Returns null when no token is
+ * found, letting the caller apply its whole-field policy.
+ */
+function splitTokenParts(
+  text: string,
+  haystack: string,
+  tokens: string[],
+): HighlightPart[] | null {
+  const sorted = [...tokens].sort((a, b) => b.length - a.length);
+  const parts: HighlightPart[] = [];
+  let matchedAny = false;
+  let cursor = 0;
+  while (cursor < text.length) {
+    let best: { index: number; token: string } | null = null;
+    for (const token of sorted) {
+      const index = firstTokenStart(haystack, token, cursor);
+      if (index === -1) continue;
+      if (best === null || index < best.index) best = { index, token };
+    }
+    if (best === null) {
+      parts.push({ text: text.slice(cursor), matched: false });
+      break;
+    }
+    if (best.index > cursor) parts.push({ text: text.slice(cursor, best.index), matched: false });
+    parts.push({ text: text.slice(best.index, best.index + best.token.length), matched: true });
+    matchedAny = true;
+    cursor = best.index + best.token.length;
+  }
+  return matchedAny ? parts : null;
+}
+
+/**
+ * Whether `text` contains the literal trimmed query (case-insensitively) —
+ * the precise, pre-fuzzy test callers use to tell a true hit from the token
+ * fallback.
+ */
+export function hasHighlightMatch(text: string, query: string): boolean {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  return needle.length > 0 && text.toLowerCase().includes(needle);
+}
+
+/**
+ * Whether `text` highlights at all for the trimmed `query`: a literal hit or,
+ * failing that, a word-start hit for any of the query's multi-character tokens.
+ * Unlike `splitHighlightParts` this never reports the whole-field fallback, so
+ * it pinpoints the result/section that genuinely mentions a fuzzy query rather
+ * than every field.
+ */
+export function hasFuzzyHighlight(text: string, query: string): boolean {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  if (!needle || !text) return false;
+  const haystack = text.toLowerCase();
+  if (haystack.includes(needle)) return true;
+  return queryTokens(needle).some((token) => firstTokenStart(haystack, token, 0) !== -1);
+}

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

@@ -0,0 +1,10 @@
+export * from "./types";
+export * from "./rpc";
+export * from "./formatters";
+export * from "./settings";
+export * from "./suite-settings";
+export * from "./async";
+export * from "./suppressed";
+export * from "./custom-pills";
+export * from "./forge";
+export * from "./highlight";

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

@@ -0,0 +1,72 @@
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+
+export interface PluginRpcContract<
+  InputSchema extends ZodType = ZodType,
+  OutputSchema extends ZodType = ZodType,
+> {
+  name: string;
+  input: InputSchema;
+  output: OutputSchema;
+}
+
+const RPC_NAME = /^[a-z][a-z0-9._-]*$/;
+
+/**
+ * Define a typed Paseo RPC contract conforming to the Paseo RPC protocol.
+ * Implemented locally without a runtime dependency on the Paseo SDK.
+ */
+export function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
+  definition: { name: string; input: InputSchema; output: OutputSchema },
+): PluginRpcContract<InputSchema, OutputSchema> {
+  const name = definition.name.trim();
+  if (!RPC_NAME.test(name)) {
+    throw new Error(`Invalid plugin RPC method: ${definition.name}`);
+  }
+  return { ...definition, name };
+}
+
+export type RpcInput<TContract> = TContract extends PluginRpcContract<infer TInput, any>
+  ? ZodInput<TInput>
+  : unknown;
+
+export type RpcOutput<TContract> = TContract extends PluginRpcContract<any, infer TOutput>
+  ? ZodOutput<TOutput>
+  : unknown;
+
+export interface DefineRpcOptions<
+  TName extends string = string,
+  TInput extends ZodType = ZodType,
+  TOutput extends ZodType = ZodType,
+> {
+  name: TName;
+  input: TInput;
+  output: TOutput;
+  description?: string;
+}
+
+/**
+ * Enhanced helper for defining a typed Paseo RPC contract with optional description.
+ */
+export function defineContract<
+  TName extends string,
+  TInput extends ZodType,
+  TOutput extends ZodType,
+>(
+  options: DefineRpcOptions<TName, TInput, TOutput>,
+): PluginRpcContract<TInput, TOutput> & { readonly description?: string } {
+  const contract = defineRpc({
+    name: options.name,
+    input: options.input,
+    output: options.output,
+  });
+
+  if (options.description) {
+    Object.defineProperty(contract, "description", {
+      value: options.description,
+      enumerable: true,
+      writable: false,
+    });
+  }
+
+  return contract as PluginRpcContract<TInput, TOutput> & { readonly description?: string };
+}

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

@@ -0,0 +1,138 @@
+import { z, type ZodType } from "zod";
+import { defineContract, type PluginRpcContract } from "./rpc";
+
+export const SettingsEmptyInputSchema = z
+  .union([z.void(), z.record(z.string(), z.unknown())])
+  .optional();
+export type SettingsEmptyInput = z.infer<typeof SettingsEmptyInputSchema>;
+
+export interface SettingsContract<TSettings extends Record<string, any>> {
+  readonly name: string;
+  readonly schema: ZodType<TSettings>;
+  readonly defaultSettings: TSettings;
+  readonly get: PluginRpcContract<ZodType<SettingsEmptyInput>, ZodType<TSettings>>;
+  readonly update: PluginRpcContract<ZodType<Partial<TSettings>>, ZodType<TSettings>>;
+  readonly reset: PluginRpcContract<ZodType<SettingsEmptyInput>, ZodType<TSettings>>;
+  readonly description?: string;
+}
+
+export interface DefineSettingsContractOptions<TSettings extends Record<string, any>> {
+  /**
+   * Unique name for the settings domain (e.g. "top.settings" or "myplugin.config").
+   * Automatically normalizes invalid RPC characters.
+   */
+  name: string;
+  /**
+   * Zod Object schema representing the full settings shape.
+   * Use `.default(...)` on fields to provide default values.
+   */
+  schema: ZodType<TSettings> & { partial?: () => ZodType<Partial<TSettings>> };
+  /**
+   * Optional default data override if schema fields do not all specify `.default()`.
+   */
+  defaultData?: Partial<TSettings>;
+  /**
+   * Optional human-readable description of the settings.
+   */
+  description?: string;
+}
+
+/**
+ * Strips `.default(...)` wrappers recursively from a Zod schema so that
+ * omitted fields remain undefined rather than being populated with default values
+ * during partial updates.
+ */
+function stripDefaults(schema: any): any {
+  if (!schema || typeof schema !== "object") {
+    return schema;
+  }
+  if (schema instanceof z.ZodDefault) {
+    return stripDefaults(schema._def.innerType);
+  }
+  if (schema instanceof z.ZodOptional) {
+    return stripDefaults(schema._def.innerType).optional();
+  }
+  if (schema instanceof z.ZodNullable) {
+    return stripDefaults(schema._def.innerType).nullable();
+  }
+  // Handle ZodEffects, ZodBranded, ZodReadonly, ZodCatch
+  if (schema._def && schema._def.schema) {
+    return stripDefaults(schema._def.schema);
+  }
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    const newShape: Record<string, any> = {};
+    for (const key of Object.keys(shape)) {
+      newShape[key] = stripDefaults(shape[key]).optional();
+    }
+    let res = z.object(newShape);
+    const unknownKeys = (schema._def as any)?.unknownKeys;
+    if (unknownKeys === "passthrough") {
+      res = res.passthrough() as any;
+    } else if (unknownKeys === "strict") {
+      res = res.strict() as any;
+    }
+    return res;
+  }
+  return typeof schema.optional === "function" ? schema.optional() : schema;
+}
+
+/**
+ * Defines a pair of typed Paseo RPC contracts (get, update, reset) for plugin settings.
+ */
+export function defineSettingsContract<TSettings extends Record<string, any>>(
+  options: DefineSettingsContractOptions<TSettings>,
+): SettingsContract<TSettings> {
+  const { name, schema, defaultData, description } = options;
+
+  let computedDefaults: TSettings;
+  try {
+    computedDefaults = schema.parse(defaultData ?? {}) as TSettings;
+  } catch {
+    computedDefaults = (defaultData ?? {}) as TSettings;
+  }
+
+  const sanitizedName = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]/g, "_");
+
+  const partialSchema = (
+    schema instanceof z.ZodObject
+      ? stripDefaults(schema)
+      : typeof (schema as any).partial === "function"
+        ? (schema as any).partial()
+        : z.record(z.string(), z.unknown())
+  ) as ZodType<Partial<TSettings>>;
+
+  const getContract = defineContract({
+    name: `${sanitizedName}.get`,
+    input: SettingsEmptyInputSchema as ZodType<SettingsEmptyInput>,
+    output: schema,
+    description: description ? `Get ${description}` : `Get ${name} settings`,
+  });
+
+  const updateContract = defineContract({
+    name: `${sanitizedName}.update`,
+    input: partialSchema,
+    output: schema,
+    description: description ? `Update ${description}` : `Update ${name} settings`,
+  });
+
+  const resetContract = defineContract({
+    name: `${sanitizedName}.reset`,
+    input: SettingsEmptyInputSchema as ZodType<SettingsEmptyInput>,
+    output: schema,
+    description: description ? `Reset ${description}` : `Reset ${name} settings to defaults`,
+  });
+
+  return {
+    name: sanitizedName,
+    schema,
+    defaultSettings: computedDefaults,
+    get: getContract,
+    update: updateContract,
+    reset: resetContract,
+    ...(description !== undefined ? { description } : {}),
+  };
+}

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

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { defineSettingsContract } from "./settings";
+
+export const SuiteSettingsSchema = z.object({
+  suiteTitle: z.string().default("xpufx Suite"),
+  accentColor: z.string().default("#6366f1"),
+  density: z.enum(["compact", "comfortable", "spacious"]).default("comfortable"),
+  showSuiteTabs: z.boolean().default(true),
+});
+
+export type SuiteSettings = z.infer<typeof SuiteSettingsSchema>;
+
+export const SuiteSettingsContract = defineSettingsContract({
+  name: "xpufx.suite.settings",
+  schema: SuiteSettingsSchema,
+  description: "Shared xpufx suite settings",
+});