@hachej/boring-workspace 0.1.0

package/dist/app-front.d.ts

@@ -0,0 +1,485 @@
+import { ComponentType } from 'react';
+import { DockviewApi } from 'dockview-react';
+import { DockviewPanelApi } from 'dockview-react';
+import { JSX } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SlashCommand } from '@hachej/boring-agent/front';
+
+/**
+ * Structural tool contract accepted from workspace plugins and UI tool
+ * factories. Kept agent-runtime-neutral so only the app integration layer
+ * needs to import @hachej/boring-agent.
+ */
+declare interface AgentTool {
+    name: string;
+    description: string;
+    promptSnippet?: string;
+    parameters: JSONSchema;
+    execute(params: Record<string, unknown>, ctx: ToolExecContext): Promise<ToolResult>;
+}
+
+declare interface AgentToolOutput {
+    /**
+     * @deprecated Executable agent tools should be contributed by server
+     * plugins. This output remains for migration only.
+     */
+    type: "agent-tool";
+    id: string;
+    tool: AgentTool;
+}
+
+/**
+ * DataExplorer shared types — no runtime deps.
+ *
+ * Importable from BOTH front and server bundles without dragging in
+ * platform-specific code.
+ */
+declare type Badge = {
+    /** 1–4 char mono code rendered as a chip. */
+    code: string;
+    tooltip?: string;
+};
+
+declare interface BindingOutput {
+    type: "binding";
+    id: string;
+    component: PluginBinding;
+}
+
+declare interface CatalogConfig {
+    id: string;
+    label: string;
+    adapter: ExplorerAdapter;
+    onSelect: (row: ExplorerRow) => void;
+    pluginId?: string;
+}
+
+declare interface CatalogOutput {
+    type: "catalog";
+    catalog: CatalogConfig;
+}
+
+declare interface ChatLayoutProps {
+    nav?: string | null;
+    navParams?: Record<string, unknown>;
+    center?: string;
+    centerParams?: Record<string, unknown>;
+    surface?: string | null;
+    surfaceParams?: Record<string, unknown>;
+    sidebar?: string | null;
+    sidebarParams?: Record<string, unknown>;
+    storageKey?: string;
+    onOpenNav?: () => void;
+    onOpenSurface?: () => void;
+    className?: string;
+}
+
+declare interface CommandConfig {
+    id: string;
+    title: string;
+    run: () => void;
+    keywords?: string[];
+    shortcut?: string;
+    when?: () => boolean;
+    pluginId?: string;
+}
+
+declare interface CommandOutput {
+    type: "command";
+    command: CommandConfig;
+}
+
+export declare function createLocalStorageSessions(opts?: CreateLocalStorageSessionsOptions): WorkspaceLocalSessionsStore;
+
+export declare interface CreateLocalStorageSessionsOptions {
+    storageKey?: string;
+    initial?: () => WorkspaceLocalSessionsState;
+}
+
+declare type ExplorerAdapter = {
+    search(args: SearchArgs): Promise<SearchResult>;
+    /** Optional. When omitted, the explorer renders flat (no facet popover). */
+    fetchFacets?(args: FacetsArgs): Promise<Facets>;
+};
+
+declare type ExplorerRow = {
+    id: string;
+    title: string;
+    /** Optional muted second line (truncates with title). */
+    subtitle?: string;
+    /** Group key — must match one of the facet values for `groupBy`. */
+    group?: string;
+    /** Leading mono chip (e.g. type code, frequency). */
+    leading?: Badge;
+    /** Trailing mono chips for status flags (e.g. [D] derived, [LIVE]). */
+    trailing?: Badge[];
+    /** Right-aligned plain text for numeric metadata (e.g. "1.2M", "2.4s"). */
+    meta?: string;
+};
+
+declare type Facets = Record<string, FacetValue[]>;
+
+declare type FacetsArgs = {
+    filters: Record<string, string[]>;
+    signal?: AbortSignal;
+};
+
+declare type FacetValue = {
+    value: string;
+    count: number;
+};
+
+declare type JSONSchema = Record<string, unknown>;
+
+declare interface LeftTabOutput<T = LeftTabParams> {
+    type: "left-tab";
+    id: string;
+    title: string;
+    icon?: PanelConfig<T>["icon"];
+    component: PanelConfig<T>["component"];
+    lazy?: PanelConfig<T>["lazy"];
+    requiresCapabilities?: PanelConfig<T>["requiresCapabilities"];
+    source?: PanelConfig<T>["source"];
+    chromeless?: PanelConfig<T>["chromeless"];
+}
+
+declare interface LeftTabParams {
+    rootDir?: string;
+    query?: string;
+    searchQuery?: string;
+    bridge?: unknown;
+    chromeless?: boolean;
+}
+
+declare type OpenArtifactHandler = (path: string) => void;
+
+declare interface OpenPanelConfig {
+    /** Panel instance id. If a panel with this id is already open, it's re-activated instead of duplicated. */
+    id: string;
+    /** Registered component id (must match a `PanelConfig.id` in WorkspaceProvider's panel registry). */
+    component: string;
+    /** Tab title. Defaults to `id`. */
+    title?: string;
+    /** Arbitrary params passed to the pane component. */
+    params?: Record<string, unknown>;
+}
+
+declare interface PanelConfig<T = any> {
+    id: string;
+    title: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Placement hint: "left" | "center" | "right" | "bottom" | "left-tab" | "right-tab" */
+    placement?: string;
+    requiresCapabilities?: string[];
+    essential?: boolean;
+    chromeless?: boolean;
+    /** Source: "builtin" | "app" */
+    source?: string;
+    pluginId?: string;
+    /**
+     * Whether to wrap the component with React.lazy + Suspense. Omit to let
+     * the registry auto-detect: zero-arg functions (factories) are treated as
+     * lazy; components that accept a props argument are treated as eager.
+     */
+    lazy?: boolean;
+    component: ComponentType<PaneProps<T>> | (() => Promise<{
+        default: ComponentType<PaneProps<T>>;
+    }>);
+}
+
+declare interface PanelOutput<T = any> {
+    type: "panel";
+    panel: PanelConfig<T>;
+}
+
+/**
+ * Unified prop shape for panel components rendered inside DockviewShell.
+ *
+ * Structurally mirrors dockview's `IDockviewPanelProps<T>` so dockview
+ * can render registered components directly — no wrapper, no field
+ * renaming, no `as` casts. We re-state the shape (rather than re-export
+ * dockview's type) so the workspace package owns its public contract:
+ * if dockview's type ever drifts, only the wiring inside DockviewShell
+ * needs to change.
+ *
+ * Use {@link definePanel} for type-safe registration.
+ *
+ * @typeParam T - Shape of the panel-specific `params` payload. Defaults
+ *   to `unknown` because layouts restored from JSON are inherently
+ *   un-typed at runtime; use a generic param when you control the
+ *   addPanel call site, otherwise read defensively.
+ */
+declare interface PaneProps<T = unknown> {
+    /** App-supplied data for this panel instance (e.g. `{ path: string }`). */
+    params: T;
+    /** Per-panel control surface (close, setActive, setTitle, …). */
+    api: DockviewPanelApi;
+    /** Top-level dockview API (groups, addPanel, removePanel, fromJSON, …). */
+    containerApi: DockviewApi;
+    /** Optional className forwarded to the pane's root element. */
+    className?: string;
+}
+
+declare type PluginBinding = ComponentType<unknown>;
+
+declare type PluginOutput = LeftTabOutput | PanelOutput | CommandOutput | CatalogOutput | BindingOutput | ProviderOutput | SurfaceResolverOutput | AgentToolOutput;
+
+declare type PluginProvider = ComponentType<PluginProviderProps>;
+
+declare interface PluginProviderProps {
+    apiBaseUrl: string;
+    authHeaders?: Record<string, string>;
+    onAuthError?: (statusCode: number) => void;
+    apiTimeout?: number;
+    children: ReactNode;
+}
+
+declare interface ProviderOutput {
+    type: "provider";
+    id: string;
+    component: PluginProvider;
+}
+
+declare type SearchArgs = {
+    query: string;
+    filters: Record<string, string[]>;
+    /** Scope to a single group's value (only set when paginating inside a group). */
+    group?: {
+        key: string;
+        value: string;
+    };
+    limit: number;
+    offset: number;
+    signal?: AbortSignal;
+};
+
+declare type SearchResult = {
+    items: ExplorerRow[];
+    /** Total count for the current scope (query + filters + optional group). */
+    total: number;
+    hasMore: boolean;
+};
+
+declare interface SessionItem {
+    id: string;
+    title: string;
+    updatedAt?: string | number;
+}
+
+declare interface SurfaceOpenRequest {
+    kind: string;
+    target: string;
+    meta?: Record<string, unknown>;
+}
+
+declare interface SurfacePanelResolution {
+    component: string;
+    id?: string;
+    title?: string;
+    params?: Record<string, unknown>;
+    score?: number;
+}
+
+declare interface SurfaceResolverConfig {
+    id: string;
+    resolve: (request: SurfaceOpenRequest) => SurfacePanelResolution | undefined;
+    source?: string;
+    pluginId?: string;
+}
+
+declare interface SurfaceResolverOutput {
+    type: "surface-resolver";
+    resolver: SurfaceResolverConfig;
+}
+
+declare interface SurfaceShellApi {
+    /** Open a file in the workbench. Idempotent — re-activates an existing pane for the same path. */
+    openFile: (path: string) => void;
+    /** Open a plugin-defined surface target through the registered surface resolvers. */
+    openSurface: (request: SurfaceOpenRequest) => void;
+    /**
+     * Open a non-file pane in the workbench. Idempotent on `id` —
+     * re-activates an existing panel with the same id rather than duplicating.
+     * Use this for app-specific panes (charts, dashboards, log viewers, …) that
+     * aren't anchored to a filesystem path.
+     */
+    openPanel: (config: OpenPanelConfig) => void;
+    /** Hide the workbench's left sources/files pane while leaving the workbench open. */
+    closeWorkbenchLeftPane: () => void;
+    /** Current snapshot of open tabs + active tab. */
+    getSnapshot: () => SurfaceShellSnapshot;
+}
+
+declare interface SurfaceShellSnapshot {
+    openTabs: SurfaceShellTab[];
+    activeTab: string | null;
+}
+
+declare interface SurfaceShellTab {
+    id: string;
+    title: string;
+    params?: Record<string, unknown>;
+}
+
+declare interface ToolExecContext {
+    abortSignal: AbortSignal;
+    toolCallId: string;
+    onUpdate?: (partial: string) => void;
+}
+
+declare interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    details?: unknown;
+}
+
+export declare function useLocalStorageSessions(store: WorkspaceLocalSessionsStore): WorkspaceLocalSessionsState;
+
+export declare type UseWorkspaceAgentSessions<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> = (options: {
+    requestHeaders: Record<string, string>;
+    storageKey: string;
+}) => WorkspaceAgentSessionsApi<TSession>;
+
+export declare function WorkspaceAgentFront<TSession extends WorkspaceAgentSession = WorkspaceAgentSession>({ workspaceId, chatPanel: chatPanelProp, useSessions: useSessionsProp, requestHeaders, sessionStorageKey, providerStorageKey, surfaceStorageKey, beforeShell, afterShell, panels, commands, catalogs, plugins, excludeDefaults, capabilities, apiBaseUrl, authHeaders, apiTimeout, defaultTheme, onThemeChange, persistenceEnabled, bridgeEndpoint, onAuthError, sessions, activeSessionId, onSwitchSession, onCreateSession, onDeleteSession, onActiveSessionIdChange, appTitle, defaultSessionTitle, topBarLeft, topBarRight, chatParams, extraPanels, extraCommands, onOpenNav, onOpenSurface, className, }: WorkspaceAgentFrontProps<TSession>): JSX.Element;
+
+export declare interface WorkspaceAgentFrontProps<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> extends Omit<WorkspaceProviderProps, "children" | "workspaceId" | "storageKey" | "chatPanel">, Omit<ChatLayoutProps, "nav" | "navParams" | "center" | "centerParams" | "surface" | "surfaceParams" | "sidebar" | "sidebarParams" | "storageKey"> {
+    workspaceId: string;
+    chatPanel?: ComponentType<WorkspaceChatPanelProps>;
+    useSessions?: UseWorkspaceAgentSessions<TSession>;
+    requestHeaders?: Record<string, string>;
+    sessionStorageKey?: string;
+    providerStorageKey?: string;
+    surfaceStorageKey?: string;
+    beforeShell?: ReactNode;
+    afterShell?: ReactNode;
+    appTitle?: string;
+    defaultSessionTitle?: string;
+    topBarLeft?: ReactNode;
+    topBarRight?: ReactNode;
+    sessions?: Array<{
+        id: string;
+        title?: string | null;
+        updatedAt?: string | number;
+    }>;
+    activeSessionId?: string | null;
+    onSwitchSession?: (id: string) => void;
+    onCreateSession?: () => void;
+    onDeleteSession?: (id: string) => void;
+    onActiveSessionIdChange?: (sessionId: string) => void;
+    chatParams?: Record<string, unknown>;
+    extraPanels?: string[];
+    extraCommands?: SlashCommand[];
+}
+
+export declare interface WorkspaceAgentSession {
+    id: string;
+    title?: string | null;
+    updatedAt?: string | number;
+}
+
+export declare interface WorkspaceAgentSessionsApi<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> {
+    sessions: TSession[];
+    loading: boolean;
+    activeSessionId?: string | null;
+    activeSession?: TSession | null;
+    switch: (id: string) => void;
+    create: (input?: {
+        title?: string;
+    }) => void | Promise<unknown>;
+    delete: (id: string) => void | Promise<unknown>;
+}
+
+export declare function WorkspaceBootGate({ workspaceId, requestHeaders, apiBaseUrl, preloadPaths, loadingFallback, errorFallback, children, }: WorkspaceBootGateProps): JSX.Element;
+
+export declare interface WorkspaceBootGateProps {
+    workspaceId: string;
+    requestHeaders?: Record<string, string>;
+    apiBaseUrl?: string | null;
+    preloadPaths?: string[];
+    loadingFallback?: ReactNode | ((status: string) => ReactNode);
+    errorFallback?: ReactNode | ((message: string) => ReactNode);
+    children: ReactNode;
+}
+
+declare type WorkspaceChatPanelComponent = ComponentType<any>;
+
+declare interface WorkspaceChatPanelProps {
+    sessionId: string;
+    onData?: (part: unknown) => void;
+    requestHeaders?: Record<string, string>;
+    onOpenArtifact?: OpenArtifactHandler;
+    className?: string;
+    /** Endpoint base for agent → visible-workbench UI commands. */
+    bridgeEndpoint?: string | null;
+    /** Imperative handle getter for the visible workbench surface. */
+    getSurface?: () => SurfaceShellApi | null;
+    /** Reads whether the visible workbench surface should be open. */
+    isWorkbenchOpen?: () => boolean;
+    /** Opens the visible workbench surface before dispatching a command. */
+    openWorkbench?: () => void;
+    [key: string]: unknown;
+}
+
+declare interface WorkspaceFrontPlugin {
+    id: string;
+    label?: string;
+    /**
+     * Context prepended to the agent's system prompt at boot. Concatenated
+     * across all registered plugins (in registration order) and joined with
+     * double-newlines. Plain Markdown. ~200-500 chars recommended.
+     */
+    systemPrompt?: string;
+    panels?: PanelConfig[];
+    commands?: CommandConfig[];
+    catalogs?: CatalogConfig[];
+    bindings?: PluginBinding[];
+    /**
+     * @deprecated Executable agent tools should be contributed by server
+     * plugins. This field remains for migration only.
+     */
+    agentTools?: AgentTool[];
+    outputs?: PluginOutput[];
+}
+
+export declare interface WorkspaceLocalSessionsState {
+    sessions: SessionItem[];
+    activeId: string;
+}
+
+export declare interface WorkspaceLocalSessionsStore {
+    getState: () => WorkspaceLocalSessionsState;
+    subscribe: (fn: () => void) => () => void;
+    switchTo: (id: string) => void;
+    create: () => void;
+    remove: (id: string) => void;
+}
+
+declare interface WorkspaceProviderProps {
+    children: ReactNode;
+    chatPanel?: WorkspaceChatPanelComponent;
+    plugins?: WorkspaceFrontPlugin[];
+    excludeDefaults?: string[];
+    panels?: PanelConfig[];
+    commands?: CommandConfig[];
+    catalogs?: CatalogConfig[];
+    capabilities?: Record<string, boolean>;
+    apiBaseUrl?: string;
+    authHeaders?: Record<string, string>;
+    /** Per-request timeout for the data layer's FetchClient, in ms. */
+    apiTimeout?: number;
+    defaultTheme?: "light" | "dark" | undefined;
+    onThemeChange?: (theme: "light" | "dark") => void;
+    workspaceId?: string;
+    storageKey?: string;
+    persistenceEnabled?: boolean;
+    bridgeEndpoint?: string | null;
+    onAuthError?: (statusCode: number) => void;
+    onOpenFile?: (path: string) => void;
+}
+
+export { }