@xpufx/paseo-top 0.4.3 → 0.4.5

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

@@ -0,0 +1,244 @@
+import type { PluginRpcContract } from "./rpc";
+
+/**
+ * Cleanup handle returned by a feature contribution.
+ *
+ * A disposer MUST be idempotent: calling it more than once must not throw and
+ * must not tear down anything twice. `composeFeatureModules` additionally
+ * wraps every disposer it receives so the *composed* teardown is idempotent
+ * even if an individual module forgets.
+ */
+export type FeatureDisposer = () => void;
+
+/**
+ * A self-contained, droppable unit of plugin functionality.
+ *
+ * A feature module owns one concern (custom pills, timeline telemetry,
+ * permission auditing, …) and exposes it through up to two contribution hooks:
+ * `contributeServer` for the daemon-side `PluginServerContext` and
+ * `contributeClient` for the client-side `PluginClientContext`. Both hooks are
+ * optional; a module may contribute to one side, both, or neither.
+ *
+ * Lifecycle contract
+ * ------------------
+ * - A contribution hook runs at most once per `contribute*` call on the
+ *   composing plugin entry.
+ * - It may return a {@link FeatureDisposer} for cleanup, or `void` when it owns
+ *   nothing to release.
+ * - Returned disposers MUST be idempotent (see {@link FeatureDisposer}).
+ * - The plugin entry composes modules with {@link composeFeatureModules} and
+ *   returns the combined disposer to Paseo.
+ * - `contracts` is declarative metadata (name-keyed RPC contracts the module
+ *   owns); it is not registered automatically. The composing entry still calls
+ *   `server.handle(contract, handler)`.
+ *
+ * Context types are generic because `paseo-plugin-helper/shared` must not
+ * import the Paseo SDK. Type a module with the SDK contexts at the call site:
+ *
+ * ```ts
+ * import type { PluginClientContext } from "@getpaseo/plugin/client";
+ * import type { PluginServerContext } from "@getpaseo/plugin/server";
+ * import type { FeatureModule } from "paseo-plugin-helper/shared";
+ *
+ * export const customPills: FeatureModule<PluginServerContext, PluginClientContext> = {
+ *   id: "custom-pills",
+ *   contracts: { list: listCustomPillsRpc },
+ *   contributeServer(server) {
+ *     const { unsubscribe } = registerCustomPillsServer(server);
+ *     return unsubscribe;
+ *   },
+ *   contributeClient(client) {
+ *     const remove = registerCustomPills(client);
+ *     return remove;
+ *   },
+ * };
+ * ```
+ */
+export interface FeatureModule<
+  TServerContext = unknown,
+  TClientContext = unknown,
+> {
+  /** Stable, plugin-unique module id (e.g. `"custom-pills"`). */
+  readonly id: string;
+  /** Daemon-side contribution. Returns an idempotent disposer, or `void`. */
+  readonly contributeServer?: (server: TServerContext) => FeatureDisposer | void;
+  /** Client-side contribution. Returns an idempotent disposer, or `void`. */
+  readonly contributeClient?: (client: TClientContext) => FeatureDisposer | void;
+  /** RPC contracts this module owns, keyed by a local name. */
+  readonly contracts?: Record<string, PluginRpcContract>;
+}
+
+/**
+ * A composed set of feature modules. `contributeServer` / `contributeClient`
+ * run every module's hook for that side and return a single combined,
+ * idempotent disposer that tears the modules down in reverse order.
+ */
+export interface FeatureComposition<
+  TServerContext = unknown,
+  TClientContext = unknown,
+> {
+  /** Module ids in composition order. */
+  readonly ids: readonly string[];
+  /** Every declared contract, flattened in module order and de-duplicated. */
+  readonly contracts: readonly PluginRpcContract[];
+  /** Run all `contributeServer` hooks; returns the combined disposer. */
+  contributeServer(server: TServerContext): FeatureDisposer;
+  /** Run all `contributeClient` hooks; returns the combined disposer. */
+  contributeClient(client: TClientContext): FeatureDisposer;
+}
+
+function toIdempotentDisposer(disposer: FeatureDisposer): FeatureDisposer {
+  let called = false;
+  return () => {
+    if (called) return;
+    called = true;
+    disposer();
+  };
+}
+
+/**
+ * Run a set of disposers in reverse (LIFO) order. Every disposer runs even if
+ * an earlier one throws; the first error is re-thrown after teardown finishes.
+ */
+function disposeAll(disposers: readonly FeatureDisposer[]): void {
+  let hasError = false;
+  let firstError: unknown;
+  for (let i = disposers.length - 1; i >= 0; i -= 1) {
+    try {
+      disposers[i]!();
+    } catch (error) {
+      if (!hasError) {
+        hasError = true;
+        firstError = error;
+      }
+    }
+  }
+  if (hasError) throw firstError;
+}
+
+/**
+ * Collect the disposers produced by a per-side contribution hook. If a module
+ * throws mid-composition, already-contributed modules are disposed before the
+ * error is re-thrown so a failed composition never leaks partial state.
+ */
+function runContributions<TServerContext, TClientContext>(
+  modules: readonly FeatureModule<TServerContext, TClientContext>[],
+  contribute: (
+    module: FeatureModule<TServerContext, TClientContext>,
+  ) => FeatureDisposer | void,
+): FeatureDisposer {
+  const disposers: FeatureDisposer[] = [];
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    disposeAll(disposers);
+  };
+
+  try {
+    for (const module of modules) {
+      const result = contribute(module);
+      if (typeof result === "function") {
+        disposers.push(toIdempotentDisposer(result));
+      }
+    }
+  } catch (error) {
+    // Roll back what already mounted, but never let a failing disposer mask
+    // the contribution error that triggered the rollback.
+    try {
+      dispose();
+    } catch {
+      // ignored
+    }
+    throw error;
+  }
+
+  return dispose;
+}
+
+function assertUniqueModules<TServerContext, TClientContext>(
+  modules: readonly FeatureModule<TServerContext, TClientContext>[],
+): void {
+  const seen = new Set<string>();
+  for (const module of modules) {
+    const id = typeof module.id === "string" ? module.id.trim() : "";
+    if (!id) {
+      throw new Error("Feature module id must be a non-empty string");
+    }
+    if (seen.has(id)) {
+      throw new Error(`Duplicate feature module id "${id}"`);
+    }
+    seen.add(id);
+  }
+}
+
+function collectContracts<TServerContext, TClientContext>(
+  modules: readonly FeatureModule<TServerContext, TClientContext>[],
+): readonly PluginRpcContract[] {
+  const contracts: PluginRpcContract[] = [];
+  const seen = new Set<string>();
+  for (const module of modules) {
+    for (const contract of Object.values(module.contracts ?? {})) {
+      if (seen.has(contract.name)) {
+        throw new Error(
+          `Duplicate RPC contract "${contract.name}" across feature modules`,
+        );
+      }
+      seen.add(contract.name);
+      contracts.push(contract);
+    }
+  }
+  return Object.freeze(contracts);
+}
+
+/**
+ * Compose {@link FeatureModule}s into one contribution unit for a plugin entry.
+ *
+ * Modules run in array order on contribution and are disposed in reverse (LIFO)
+ * order. The returned combined disposer is idempotent: calling it twice runs
+ * teardown once and never throws the first error a second time.
+ *
+ * ```ts
+ * import type { PluginClientContext } from "@getpaseo/plugin/client";
+ * import type { PluginServerContext } from "@getpaseo/plugin/server";
+ * import { composeFeatureModules } from "paseo-plugin-helper/shared";
+ * import { customPills } from "./features/custom-pills";
+ * import { timelineTelemetry } from "./features/timeline-telemetry";
+ *
+ * const features = composeFeatureModules<PluginServerContext, PluginClientContext>([
+ *   customPills,
+ *   timelineTelemetry,
+ * ]);
+ *
+ * export function contributeServer(server: PluginServerContext) {
+ *   return features.contributeServer(server);
+ * }
+ *
+ * export function contributeClient(client: PluginClientContext) {
+ *   return features.contributeClient(client);
+ * }
+ * ```
+ *
+ * @throws if two modules share an `id` or declare the same RPC contract `name`.
+ */
+export function composeFeatureModules<
+  TServerContext = unknown,
+  TClientContext = unknown,
+>(
+  modules: readonly FeatureModule<TServerContext, TClientContext>[],
+): FeatureComposition<TServerContext, TClientContext> {
+  const list = [...modules];
+  assertUniqueModules(list);
+  const contracts = collectContracts(list);
+
+  return {
+    ids: Object.freeze(list.map((module) => module.id)),
+    contracts,
+    contributeServer(server) {
+      return runContributions(list, (module) => module.contributeServer?.(server));
+    },
+    contributeClient(client) {
+      return runContributions(list, (module) => module.contributeClient?.(client));
+    },
+  };
+}

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

@@ -108,3 +108,30 @@ export function resolveForgeMark(
   const resolved = isForgeKind(explicit) ? explicit : forgeKindFromHost(host);
   return FORGE_MARKS[resolved];
 }
+
+/**
+ * Official monochrome forge marks (Simple Icons, CC0 / project trademarks),
+ * authored on a 24x24 viewBox. Rendered as inline SVG through a data URI so a
+ * consumer needs no SVG dependency: exact vector marks on web/Electron, where
+ * Paseo renders React Native Web, and a Lucide fallback on native.
+ *
+ * Pure and React-free so it lives in `shared/` next to the resolver.
+ */
+const FORGE_MARK_PATHS: Partial<Record<ForgeKind, string>> = {
+  codeberg:
+    "M11.999.747A11.974 11.974 0 0 0 0 12.75c0 2.254.635 4.465 1.833 6.376L11.837 6.19c.072-.092.251-.092.323 0l4.178 5.402h-2.992l.065.239h3.113l.882 1.138h-3.674l.103.374h3.86l.777 1.003h-4.358l.135.483h4.593l.695.894h-5.038l.165.589h5.326l.609.785h-5.717l.182.65h6.038l.562.727h-6.397l.183.65h6.717A12.003 12.003 0 0 0 24 12.75 11.977 11.977 0 0 0 11.999.747zm3.654 19.104.182.65h5.326c.173-.204.353-.433.513-.65zm.385 1.377.18.65h3.563c.233-.198.485-.428.712-.65zm.383 1.377.182.648h1.203c.356-.204.685-.412 1.042-.648zz",
+  forgejo:
+    "M16.7773 0c1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.1175a7.0759 7.0759 0 0 1 4.148-1.4205l.1176-.001 1.3385.0002c.4973-.8827 1.4434-1.4788 2.5288-1.4788 1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.319c.8827.4973 1.4788 1.4434 1.4788 2.5287 0 1.602-1.2986 2.9005-2.9005 2.9005-1.6018 0-2.9004-1.2986-2.9004-2.9005 0-1.0853.596-2.0314 1.4788-2.5287l-.0002-9.9831c0-3.887 3.1195-7.0453 6.9915-7.108l.1176-.001h1.3385C14.7458.5962 15.692 0 16.7773 0ZM7.2227 19.9052c-.6596 0-1.1943.5347-1.1943 1.1943s.5347 1.1943 1.1943 1.1943 1.1944-.5347 1.1944-1.1943-.5348-1.1943-1.1944-1.1943Zm9.5546-10.4644c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Zm0-7.7346c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Z",
+  gitea:
+    "M4.209 4.603c-.247 0-.525.02-.84.088-.333.07-1.28.283-2.054 1.027C-.403 7.25.035 9.685.089 10.052c.065.446.263 1.687 1.21 2.768 1.749 2.141 5.513 2.092 5.513 2.092s.462 1.103 1.168 2.119c.955 1.263 1.936 2.248 2.89 2.367 2.406 0 7.212-.004 7.212-.004s.458.004 1.08-.394c.535-.324 1.013-.893 1.013-.893s.492-.527 1.18-1.73c.21-.37.385-.729.538-1.068 0 0 2.107-4.471 2.107-8.823-.042-1.318-.367-1.55-.443-1.627-.156-.156-.366-.153-.366-.153s-4.475.252-6.792.306c-.508.011-1.012.023-1.512.027v4.474l-.634-.301c0-1.39-.004-4.17-.004-4.17-1.107.016-3.405-.084-3.405-.084s-5.399-.27-5.987-.324c-.187-.011-.401-.032-.648-.032zm.354 1.832h.111s.271 2.269.6 3.597C5.549 11.147 6.22 13 6.22 13s-.996-.119-1.641-.348c-.99-.324-1.409-.714-1.409-.714s-.73-.511-1.096-1.52C1.444 8.73 2.021 7.7 2.021 7.7s.32-.859 1.47-1.145c.395-.106.863-.12 1.072-.12zm8.33 2.554c.26.003.509.127.509.127l.868.422-.529 1.075a.686.686 0 0 0-.614.359.685.685 0 0 0 .072.756l-.939 1.924a.69.69 0 0 0-.66.527.687.687 0 0 0 .347.763.686.686 0 0 0 .867-.206.688.688 0 0 0-.069-.882l.916-1.874a.667.667 0 0 0 .237-.02.657.657 0 0 0 .271-.137 8.826 8.826 0 0 1 1.016.512.761.761 0 0 1 .286.282c.073.21-.073.569-.073.569-.087.29-.702 1.55-.702 1.55a.692.692 0 0 0-.676.477.681.681 0 1 0 1.157-.252c.073-.141.141-.282.214-.431.19-.397.515-1.16.515-1.16.035-.066.218-.394.103-.814-.095-.435-.48-.638-.48-.638-.467-.301-1.116-.58-1.116-.58s0-.156-.042-.27a.688.688 0 0 0-.148-.241l.516-1.062 2.89 1.401s.48.218.583.619c.073.282-.019.534-.069.657-.24.587-2.1 4.317-2.1 4.317s-.232.554-.748.588a1.065 1.065 0 0 1-.393-.045l-.202-.08-4.31-2.1s-.417-.218-.49-.596c-.083-.31.104-.691.104-.691l2.073-4.272s.183-.37.466-.497a.855.855 0 0 1 .35-.077z",
+};
+
+/** Inline SVG data URI for a custom mark, tinted with the resolved color. */
+export function forgeMarkSource(kind: ForgeKind, color: string): { uri: string } | null {
+  const path = FORGE_MARK_PATHS[kind];
+  if (!path) return null;
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">` +
+    `<path fill="${color}" d="${path}"/></svg>`;
+  return { uri: `data:image/svg+xml,${encodeURIComponent(svg)}` };
+}

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

@@ -1,5 +1,6 @@
 export * from "./types";
 export * from "./rpc";
+export * from "./features";
 export * from "./formatters";
 export * from "./settings";
 export * from "./suite-settings";
@@ -8,3 +9,4 @@ export * from "./suppressed";
 export * from "./custom-pills";
 export * from "./forge";
 export * from "./highlight";
+export * from "./tickets";