@evermore.work/plugin-sdk 2026.509.0-canary.0

package/dist/ui/types.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Evermore plugin UI SDK — types for plugin frontend components.
+ *
+ * Plugin UI bundles import from `@evermore.work/plugin-sdk/ui`.  This subpath
+ * provides the bridge hooks, component prop interfaces, and error types that
+ * plugin React components use to communicate with the host.
+ *
+ * Plugin UI bundles are loaded as ES modules into designated extension slots.
+ * All communication with the plugin worker goes through the host bridge — plugin
+ * components must NOT access host internals or call host APIs directly.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ * @see PLUGIN_SPEC.md §19.0.1 — Plugin UI SDK
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ */
+import type { AnchorHTMLAttributes, MouseEvent as ReactMouseEvent } from "react";
+import type { PluginBridgeErrorCode } from "@evermore.work/shared";
+import type { PluginLauncherRenderContextSnapshot, PluginModalBoundsRequest, PluginRenderCloseEvent } from "../protocol.js";
+export type { PluginBridgeErrorCode, PluginLauncherBounds, PluginLauncherRenderEnvironment, } from "@evermore.work/shared";
+export type { PluginLauncherRenderContextSnapshot, PluginModalBoundsRequest, PluginRenderCloseEvent, } from "../protocol.js";
+/**
+ * Structured error returned by the bridge when a UI → worker call fails.
+ *
+ * Plugin components receive this in `usePluginData()` as the `error` field
+ * and may encounter it as a thrown value from `usePluginAction()`.
+ *
+ * Error codes:
+ * - `WORKER_UNAVAILABLE` — plugin worker is not running
+ * - `CAPABILITY_DENIED` — plugin lacks the required capability
+ * - `WORKER_ERROR` — worker returned an error from its handler
+ * - `TIMEOUT` — worker did not respond within the configured timeout
+ * - `UNKNOWN` — unexpected bridge-level failure
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export interface PluginBridgeError {
+    /** Machine-readable error code. */
+    code: PluginBridgeErrorCode;
+    /** Human-readable error message. */
+    message: string;
+    /**
+     * Original error details from the worker, if available.
+     * Only present when `code === "WORKER_ERROR"`.
+     */
+    details?: unknown;
+}
+/**
+ * Read-only host context passed to every plugin component via `useHostContext()`.
+ *
+ * Plugin components use this to know which company, project, or entity is
+ * currently active so they can scope their data requests accordingly.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export interface PluginHostContext {
+    /** UUID of the currently active company, if any. */
+    companyId: string | null;
+    /** URL prefix for the current company (e.g. `"my-company"`). */
+    companyPrefix: string | null;
+    /** UUID of the currently active project, if any. */
+    projectId: string | null;
+    /** UUID of the current entity (for detail tab contexts), if any. */
+    entityId: string | null;
+    /** Type of the current entity (e.g. `"issue"`, `"agent"`). */
+    entityType: string | null;
+    /**
+     * UUID of the parent entity when rendering nested slots.
+     * For `commentAnnotation` slots this is the issue ID containing the comment.
+     */
+    parentEntityId?: string | null;
+    /** UUID of the current authenticated user. */
+    userId: string | null;
+    /** Runtime metadata for the host container currently rendering this plugin UI. */
+    renderEnvironment?: PluginRenderEnvironmentContext | null;
+}
+/**
+ * Async-capable callback invoked during a host-managed close lifecycle.
+ */
+export type PluginRenderCloseHandler = (event: PluginRenderCloseEvent) => void | Promise<void>;
+/**
+ * Close lifecycle hooks available when the plugin UI is rendered inside a
+ * host-managed launcher environment.
+ */
+export interface PluginRenderCloseLifecycle {
+    /** Register a callback before the host closes the current environment. */
+    onBeforeClose?(handler: PluginRenderCloseHandler): () => void;
+    /** Register a callback after the host closes the current environment. */
+    onClose?(handler: PluginRenderCloseHandler): () => void;
+}
+/**
+ * Runtime information about the host container currently rendering a plugin UI.
+ */
+export interface PluginRenderEnvironmentContext extends PluginLauncherRenderContextSnapshot {
+    /** Optional host callback for requesting new bounds while a modal is open. */
+    requestModalBounds?(request: PluginModalBoundsRequest): Promise<void>;
+    /** Optional close lifecycle callbacks for host-managed overlays. */
+    closeLifecycle?: PluginRenderCloseLifecycle | null;
+}
+/**
+ * Options for host-managed Evermore navigation from plugin UI.
+ */
+export interface HostNavigationOptions {
+    /** Replace the current history entry instead of pushing a new one. */
+    replace?: boolean;
+    /** Optional state forwarded to the host router. */
+    state?: unknown;
+}
+/**
+ * Options for `useHostNavigation().linkProps()`.
+ */
+export interface HostNavigationLinkOptions extends HostNavigationOptions {
+    /** Standard anchor target. Non-`_self` targets are not intercepted. */
+    target?: AnchorHTMLAttributes<HTMLAnchorElement>["target"];
+    /** Standard anchor rel attribute. */
+    rel?: AnchorHTMLAttributes<HTMLAnchorElement>["rel"];
+}
+/**
+ * Anchor props returned by `useHostNavigation().linkProps()`.
+ *
+ * The `href` is always real so browser affordances such as copy-link,
+ * modifier-click, middle-click, and open-in-new-tab continue to work.
+ */
+export interface HostNavigationLinkProps extends Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "target" | "rel"> {
+    onClick: (event: ReactMouseEvent<HTMLAnchorElement>) => void;
+}
+/**
+ * Snapshot of the host router location, exposed to plugin UI through
+ * `useHostLocation()`. Mirrors the relevant subset of `Location` from
+ * `react-router-dom` so plugins can react to URL changes without importing
+ * router internals.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export interface HostLocation {
+    /** Current pathname, e.g. `/EVR/wiki`. */
+    pathname: string;
+    /** Current search string, e.g. `?tab=config` (includes the leading `?`). */
+    search: string;
+    /** Current hash, e.g. `#document-plan` (includes the leading `#`). */
+    hash: string;
+    /** Optional state forwarded by the host router for same-tab SPA navigation. */
+    state?: unknown;
+}
+/**
+ * Host-managed navigation helpers for plugin UI.
+ */
+export interface HostNavigation {
+    /**
+     * Resolve a Evermore-internal path using the active company prefix.
+     *
+     * For example, in company `EVR`, `resolveHref("/wiki")` returns
+     * `"/EVR/wiki"`, while `resolveHref("/EVR/wiki")` stays unchanged.
+     */
+    resolveHref(to: string): string;
+    /** Navigate through the host router without reloading the document. */
+    navigate(to: string, options?: HostNavigationOptions): void;
+    /**
+     * Build anchor props for host-managed links.
+     *
+     * Plain left-clicks are routed through the host SPA router. Browser-native
+     * link gestures are left alone because the returned props include a real
+     * `href`.
+     */
+    linkProps(to: string, options?: HostNavigationLinkOptions): HostNavigationLinkProps;
+}
+/**
+ * Props passed to a plugin page component.
+ *
+ * A page is a full-page extension at `/plugins/:pluginId` or `/:company/plugins/:pluginId`.
+ *
+ * @see PLUGIN_SPEC.md §19.1 — Global Operator Routes
+ * @see PLUGIN_SPEC.md §19.2 — Company-Context Routes
+ */
+export interface PluginPageProps {
+    /** The current host context. */
+    context: PluginHostContext;
+}
+/**
+ * Props passed to a plugin dashboard widget component.
+ *
+ * A dashboard widget is rendered as a card or section on the main dashboard.
+ *
+ * @see PLUGIN_SPEC.md §19.4 — Dashboard Widgets
+ */
+export interface PluginWidgetProps {
+    /** The current host context. */
+    context: PluginHostContext;
+}
+/**
+ * Props passed to a plugin detail tab component.
+ *
+ * A detail tab is rendered as an additional tab on a project, issue, agent,
+ * goal, or run detail page.
+ *
+ * @see PLUGIN_SPEC.md §19.3 — Detail Tabs
+ */
+export interface PluginDetailTabProps {
+    /** The current host context, always including `entityId` and `entityType`. */
+    context: PluginHostContext & {
+        entityId: string;
+        entityType: string;
+    };
+}
+/**
+ * Props passed to a plugin sidebar component.
+ *
+ * A sidebar entry adds a link or section to the application sidebar.
+ *
+ * @see PLUGIN_SPEC.md §19.5 — Sidebar Entries
+ */
+export interface PluginSidebarProps {
+    /** The current host context. */
+    context: PluginHostContext;
+}
+/**
+ * Props passed to a plugin route sidebar component.
+ *
+ * A route sidebar replaces the normal company sidebar while the user is on a
+ * matching plugin page route declared with the same `routePath`.
+ *
+ * @see PLUGIN_SPEC.md §19.5 — Sidebar Entries
+ */
+export interface PluginRouteSidebarProps {
+    /** The current host context. */
+    context: PluginHostContext;
+}
+/**
+ * Props passed to a plugin project sidebar item component.
+ *
+ * A project sidebar item is rendered **once per project** under that project's
+ * row in the sidebar Projects list. The host passes the current project's id
+ * in `context.entityId` and `context.entityType` is `"project"`.
+ *
+ * Use this slot to add a link (e.g. "Files", "Linear Sync") that navigates to
+ * the project detail with a plugin tab selected: `/projects/:projectRef?tab=plugin:key:slotId`.
+ *
+ * @see PLUGIN_SPEC.md §19.5.1 — Project sidebar items
+ */
+export interface PluginProjectSidebarItemProps {
+    /** Host context plus entityId (project id) and entityType "project". */
+    context: PluginHostContext & {
+        entityId: string;
+        entityType: "project";
+    };
+}
+/**
+ * Props passed to a plugin comment annotation component.
+ *
+ * A comment annotation is rendered below each individual comment in the
+ * issue detail timeline. The host passes the comment ID as `entityId`
+ * and `"comment"` as `entityType`, plus the parent issue ID as
+ * `parentEntityId` so the plugin can scope data fetches to both.
+ *
+ * Use this slot to augment comments with parsed file links, sentiment
+ * badges, inline actions, or any per-comment metadata.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Comment Annotations
+ */
+export interface PluginCommentAnnotationProps {
+    /** Host context with comment and parent issue identifiers. */
+    context: PluginHostContext & {
+        /** UUID of the comment being annotated. */
+        entityId: string;
+        /** Always `"comment"` for comment annotation slots. */
+        entityType: "comment";
+        /** UUID of the parent issue containing this comment. */
+        parentEntityId: string;
+    };
+}
+/**
+ * Props passed to a plugin comment context menu item component.
+ *
+ * A comment context menu item is rendered in a "more" dropdown menu on
+ * each comment in the issue detail timeline. The host passes the comment
+ * ID as `entityId` and `"comment"` as `entityType`, plus the parent
+ * issue ID as `parentEntityId`.
+ *
+ * Use this slot to add per-comment actions such as "Create sub-issue from
+ * comment", "Translate", "Flag for review", or any custom plugin action.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Comment Context Menu Items
+ */
+export interface PluginCommentContextMenuItemProps {
+    /** Host context with comment and parent issue identifiers. */
+    context: PluginHostContext & {
+        /** UUID of the comment this menu item acts on. */
+        entityId: string;
+        /** Always `"comment"` for comment context menu item slots. */
+        entityType: "comment";
+        /** UUID of the parent issue containing this comment. */
+        parentEntityId: string;
+    };
+}
+/**
+ * Props passed to a plugin settings page component.
+ *
+ * Overrides the auto-generated JSON Schema form when the plugin declares
+ * a `settingsPage` UI slot. The component is responsible for reading and
+ * writing config through the bridge.
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Plugin Settings UI
+ */
+export interface PluginSettingsPageProps {
+    /** The current host context. */
+    context: PluginHostContext;
+}
+/**
+ * Return value of `usePluginData(key, params)`.
+ *
+ * Mirrors a standard async data-fetching hook pattern:
+ * exactly one of `data` or `error` is non-null at any time (unless `loading`).
+ *
+ * @template T The type of the data returned by the worker handler
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export interface PluginDataResult<T = unknown> {
+    /** The data returned by the worker's `getData` handler. `null` while loading or on error. */
+    data: T | null;
+    /** `true` while the initial request or a refresh is in flight. */
+    loading: boolean;
+    /** Bridge error if the request failed. `null` on success or while loading. */
+    error: PluginBridgeError | null;
+    /**
+     * Manually trigger a data refresh.
+     * Useful for poll-based updates or post-action refreshes.
+     */
+    refresh(): void;
+}
+export type PluginToastTone = "info" | "success" | "warn" | "error";
+export interface PluginToastAction {
+    label: string;
+    href: string;
+}
+export interface PluginToastInput {
+    id?: string;
+    dedupeKey?: string;
+    title: string;
+    body?: string;
+    tone?: PluginToastTone;
+    ttlMs?: number;
+    action?: PluginToastAction;
+}
+export type PluginToastFn = (input: PluginToastInput) => string | null;
+/**
+ * Return value of `usePluginStream<T>(channel)`.
+ *
+ * Provides a growing array of events pushed from the plugin worker via SSE,
+ * plus connection status metadata.
+ *
+ * @template T The type of each event emitted by the worker
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+export interface PluginStreamResult<T = unknown> {
+    /** All events received so far, in arrival order. */
+    events: T[];
+    /** The most recently received event, or `null` if none yet. */
+    lastEvent: T | null;
+    /** `true` while the SSE connection is being established. */
+    connecting: boolean;
+    /** `true` once the SSE connection is open and receiving events. */
+    connected: boolean;
+    /** Error if the SSE connection failed or was interrupted. `null` otherwise. */
+    error: Error | null;
+    /** Close the SSE connection and stop receiving events. */
+    close(): void;
+}
+/**
+ * Return value of `usePluginAction(key)`.
+ *
+ * Returns an async function that, when called, sends an action request
+ * to the worker's `performAction` handler and returns the result.
+ *
+ * On failure, the async function throws a `PluginBridgeError`.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ *
+ * @example
+ * ```tsx
+ * const resync = usePluginAction("resync");
+ * <button onClick={() => resync({ companyId }).catch(err => console.error(err))}>
+ *   Resync Now
+ * </button>
+ * ```
+ */
+export type PluginActionFn = (params?: Record<string, unknown>) => Promise<unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/ui/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ui/types.ts"],"names":[],"mappings":"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"}

package/dist/ui/types.js

@@ -0,0 +1,17 @@
+/**
+ * Evermore plugin UI SDK — types for plugin frontend components.
+ *
+ * Plugin UI bundles import from `@evermore.work/plugin-sdk/ui`.  This subpath
+ * provides the bridge hooks, component prop interfaces, and error types that
+ * plugin React components use to communicate with the host.
+ *
+ * Plugin UI bundles are loaded as ES modules into designated extension slots.
+ * All communication with the plugin worker goes through the host bridge — plugin
+ * components must NOT access host internals or call host APIs directly.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ * @see PLUGIN_SPEC.md §19.0.1 — Plugin UI SDK
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/ui/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/ui/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/worker-rpc-host.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Worker-side RPC host — runs inside the child process spawned by the host.
+ *
+ * This module is the worker-side counterpart to the server's
+ * `PluginWorkerManager`. It:
+ *
+ * 1. Reads newline-delimited JSON-RPC 2.0 requests from **stdin**
+ * 2. Dispatches them to the appropriate plugin handler (events, jobs, tools, …)
+ * 3. Writes JSON-RPC 2.0 responses back on **stdout**
+ * 4. Provides a concrete `PluginContext` whose SDK client methods (e.g.
+ *    `ctx.state.get()`, `ctx.events.emit()`) send JSON-RPC requests to the
+ *    host on stdout and await responses on stdin.
+ *
+ * ## Message flow
+ *
+ * ```
+ * Host (parent)                          Worker (this module)
+ *   |                                        |
+ *   |--- request(initialize) ------------->  |  → calls plugin.setup(ctx)
+ *   |<-- response(ok:true) ----------------  |
+ *   |                                        |
+ *   |--- notification(onEvent) ----------->  |  → dispatches to registered handler
+ *   |                                        |
+ *   |<-- request(state.get) ---------------  |  ← SDK client call from plugin code
+ *   |--- response(result) ---------------->  |
+ *   |                                        |
+ *   |--- request(shutdown) --------------->  |  → calls plugin.onShutdown()
+ *   |<-- response(void) ------------------  |
+ *   |                                        (process exits)
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+import type { EvermorePlugin } from "./define-plugin.js";
+/**
+ * Options for starting the worker-side RPC host.
+ */
+export interface WorkerRpcHostOptions {
+    /**
+     * The plugin definition returned by `definePlugin()`.
+     *
+     * The worker entrypoint should import its plugin and pass it here.
+     */
+    plugin: EvermorePlugin;
+    /**
+     * Input stream to read JSON-RPC messages from.
+     * Defaults to `process.stdin`.
+     */
+    stdin?: NodeJS.ReadableStream;
+    /**
+     * Output stream to write JSON-RPC messages to.
+     * Defaults to `process.stdout`.
+     */
+    stdout?: NodeJS.WritableStream;
+    /**
+     * Default timeout (ms) for worker→host RPC calls.
+     * Defaults to 30 000 ms.
+     */
+    rpcTimeoutMs?: number;
+}
+/**
+ * A running worker RPC host instance.
+ *
+ * Returned by `startWorkerRpcHost()`. Callers (usually just the worker
+ * bootstrap) hold a reference so they can inspect status or force-stop.
+ */
+export interface WorkerRpcHost {
+    /** Whether the host is currently running and listening for messages. */
+    readonly running: boolean;
+    /**
+     * Stop the RPC host immediately. Closes readline, rejects pending
+     * outbound calls, and does NOT call the plugin's shutdown hook (that
+     * should have already been called via the `shutdown` RPC method).
+     */
+    stop(): void;
+}
+/**
+ * Options for runWorker when testing (optional stdio to avoid using process streams).
+ * When both stdin and stdout are provided, the "is main module" check is skipped
+ * and the host is started with these streams. Used by tests.
+ */
+export interface RunWorkerOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}
+/**
+ * Start the worker when this module is the process entrypoint.
+ *
+ * Call this at the bottom of your worker file so that when the host runs
+ * `node dist/worker.js`, the RPC host starts and the process stays alive.
+ * When the module is imported (e.g. for re-exports or tests), nothing runs.
+ *
+ * When `options.stdin` and `options.stdout` are provided (e.g. in tests),
+ * the main-module check is skipped and the host is started with those streams.
+ *
+ * @example
+ * ```ts
+ * const plugin = definePlugin({ ... });
+ * export default plugin;
+ * runWorker(plugin, import.meta.url);
+ * ```
+ */
+export declare function runWorker(plugin: EvermorePlugin, moduleUrl: string, options?: RunWorkerOptions): WorkerRpcHost | void;
+/**
+ * Start the worker-side RPC host.
+ *
+ * This function is typically called from a thin bootstrap script that is the
+ * actual entrypoint of the child process:
+ *
+ * ```ts
+ * // worker-bootstrap.ts
+ * import plugin from "./worker.js";
+ * import { startWorkerRpcHost } from "@evermore.work/plugin-sdk";
+ *
+ * startWorkerRpcHost({ plugin });
+ * ```
+ *
+ * The host begins listening on stdin immediately. It does NOT call
+ * `plugin.definition.setup()` yet — that happens when the host sends the
+ * `initialize` RPC.
+ *
+ * @returns A handle for inspecting or stopping the RPC host
+ */
+export declare function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost;
+//# sourceMappingURL=worker-rpc-host.d.ts.map

package/dist/worker-rpc-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-rpc-host.d.ts","sourceRoot":"","sources":["../src/worker-rpc-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAaH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAiEzD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,EAAE,cAAc,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAE9B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAE/B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAuBD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,aAAa,GAAG,IAAI,CAkBtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAq4C/E"}