@hachej/boring-workspace 0.1.70 → 0.1.72

package/dist/src/shared/types/panel.d.ts

@@ -0,0 +1,123 @@
+import { ComponentType } from 'react';
+import { DockviewApi, DockviewPanelApi } from 'dockview-react';
+/**
+ * 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.
+ */
+export 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;
+}
+export interface WorkspaceSourceOpenPanelConfig {
+    id: string;
+    component: string;
+    title?: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Props for workspace source panes hosted in the left workspace rail.
+ * These are not Dockview panels: they receive only source-pane params and
+ * the explicit actions that the source host supports.
+ */
+export interface WorkspaceSourceProps<T = unknown> {
+    params: T;
+    className?: string;
+    openPanel?: (config: WorkspaceSourceOpenPanelConfig) => void;
+}
+export type PanelPlacement = "left" | "center" | "right" | "bottom" | "shared-dockview" | "workspace-page" | "right-tab";
+export declare function isSharedDockviewPlacement(placement: string | undefined): boolean;
+export declare function isWorkspacePagePlacement(placement: string | undefined): boolean;
+export interface PanelConfig<T = any> {
+    id: string;
+    title: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Placement hint. Public plugin placements: "workspace-page" | "shared-dockview". */
+    placement?: PanelPlacement | string;
+    requiresCapabilities?: string[];
+    essential?: boolean;
+    chromeless?: boolean;
+    supportsFullPage?: boolean;
+    /** Source: "builtin" | "app" */
+    source?: string;
+    pluginId?: string;
+    /** Revision emitted by the runtime plugin asset manager for hot-loaded panels. */
+    pluginRevision?: number;
+    /**
+     * 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>>;
+    }>);
+}
+export type PanelRegistration<T = any> = Omit<PanelConfig<T>, 'id'>;
+export interface WorkspaceSourceConfig<T = any> {
+    id: string;
+    title: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    component: ComponentType<WorkspaceSourceProps<T>> | (() => Promise<{
+        default: ComponentType<WorkspaceSourceProps<T>>;
+    }>);
+    requiresCapabilities?: string[];
+    chromeless?: boolean;
+    /** Panel id opened in the main workspace when this source is selected. */
+    defaultPanelId?: string;
+    /** Source: "builtin" | "app" */
+    source?: string;
+    pluginId?: string;
+    /** Revision emitted by the runtime plugin asset manager for hot-loaded sources. */
+    pluginRevision?: number;
+    lazy?: boolean;
+}
+export type WorkspaceSourceRegistration<T = any> = Omit<WorkspaceSourceConfig<T>, 'id'>;
+/**
+ * Identity helper for type-safe panel registration. Pure runtime
+ * passthrough — the value of this is forcing TypeScript to verify that
+ * the registered component accepts the params shape declared on the
+ * config. Without it, apps tend to widen `component` to
+ * `ComponentType<PaneProps<unknown>>` and lose the link.
+ *
+ * ```ts
+ * const editorPanel = definePanel<{ path: string }>({
+ *   id: "code-editor",
+ *   title: "Editor",
+ *   component: CodeEditorPane, // typechecked against PaneProps<{ path: string }>
+ *   placement: "center",
+ * })
+ * ```
+ */
+export declare function definePanel<T = unknown>(config: PanelConfig<T>): PanelConfig<T>;
+export interface CommandConfig {
+    id: string;
+    title: string;
+    run: () => void;
+    keywords?: string[];
+    shortcut?: string;
+    when?: () => boolean;
+    pluginId?: string;
+}

package/dist/src/shared/types/surface.d.ts

@@ -0,0 +1,42 @@
+import { FilesystemId } from './filesystem';
+export declare const WORKSPACE_OPEN_PATH_SURFACE_KIND = "workspace.open.path";
+export interface SurfaceOpenRequest {
+    kind: string;
+    target: string;
+    filesystem?: FilesystemId;
+    meta?: Record<string, unknown>;
+}
+export interface SurfacePanelResolution {
+    component: string;
+    id?: string;
+    title?: string;
+    params?: Record<string, unknown>;
+    score?: number;
+}
+export interface SurfaceResolverExample {
+    target: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+export interface SurfaceResolverMetadata {
+    kind?: string;
+    title?: string;
+    description?: string;
+    targetHint?: string;
+    examples?: SurfaceResolverExample[];
+    metaSchema?: Record<string, unknown>;
+}
+export interface SurfaceResolverDescriptor extends SurfaceResolverMetadata {
+    id: string;
+    kind: string;
+    source?: string;
+    pluginId?: string;
+}
+export interface SurfaceResolverConfig extends SurfaceResolverMetadata {
+    id: string;
+    resolve: (request: SurfaceOpenRequest) => SurfacePanelResolution | undefined;
+    source?: string;
+    pluginId?: string;
+}
+export type SurfaceResolverRegistration = Omit<SurfaceResolverConfig, "id">;
+export declare function surfaceResolverDescriptor(resolver: SurfaceResolverConfig): SurfaceResolverDescriptor | null;

package/dist/src/shared/ui-bridge.d.ts

@@ -0,0 +1,77 @@
+import { FilesystemId } from './types/filesystem';
+export interface UiBridge {
+    getState(): Promise<UiState | null>;
+    setState(state: UiState): Promise<void>;
+    /** Canonical UI command dispatch method. */
+    postCommand(cmd: UiCommand): Promise<CommandResult>;
+    subscribeCommands(handler: (cmd: UiCommand & {
+        seq: number;
+    }) => unknown): () => void;
+    drainCommands?(): Promise<Array<UiCommand & {
+        seq: number;
+    }>>;
+}
+export type WorkspaceBridge = UiBridge & {
+    /** @deprecated Use postCommand. Kept as a compatibility alias for WorkspaceBridge RPC callers. */
+    emitUiEffect(cmd: UiCommand): Promise<CommandResult>;
+};
+export type UiState = Record<string, unknown>;
+export type UiCommand = {
+    kind: 'openFile';
+    params: {
+        path: string;
+        mode?: 'view' | 'edit' | 'diff';
+        filesystem?: FilesystemId;
+    };
+} | {
+    kind: 'openSurface';
+    params: {
+        kind: string;
+        target: string;
+        filesystem?: FilesystemId;
+        meta?: Record<string, unknown>;
+    };
+} | {
+    kind: 'openPanel';
+    params: {
+        id: string;
+        component: string;
+        params?: Record<string, unknown>;
+    };
+} | {
+    kind: 'closePanel';
+    params: {
+        id: string;
+    };
+} | {
+    kind: 'closeWorkbenchLeftPane';
+    params: Record<string, never>;
+} | {
+    kind: 'showNotification';
+    params: {
+        msg: string;
+        level?: 'info' | 'warn' | 'error';
+    };
+} | {
+    kind: 'navigateToLine';
+    params: {
+        file: string;
+        line: number;
+    };
+} | {
+    kind: 'expandToFile';
+    params: {
+        path: string;
+    };
+} | {
+    kind: string;
+    params: Record<string, unknown>;
+};
+export interface CommandResult {
+    seq: number;
+    status: 'ok' | 'error';
+    error?: {
+        code: string;
+        message: string;
+    };
+}

package/dist/src/shared/workspace-bridge-rpc.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Platform-neutral WorkspaceBridge RPC contracts.
+ *
+ * This file is imported by both browser and server bundles. Keep it free of
+ * Node-only types/imports and keep stable bridge error codes centralized here.
+ */
+/**
+ * Canonical WorkspaceBridge runtime env var names. Defined in this browser- and
+ * server-safe module so the producer (server runtimeEnv injection) and the
+ * consumer (bridge-client SDK) share one source of truth and cannot drift on
+ * string equality.
+ */
+export declare const WORKSPACE_BRIDGE_URL_ENV = "BORING_WORKSPACE_BRIDGE_URL";
+export declare const WORKSPACE_BRIDGE_TOKEN_ENV = "BORING_WORKSPACE_BRIDGE_TOKEN";
+export declare const WORKSPACE_BRIDGE_TOKEN_URL_ENV = "BORING_WORKSPACE_BRIDGE_TOKEN_URL";
+export declare const WORKSPACE_BRIDGE_REFRESH_TOKEN_ENV = "BORING_WORKSPACE_BRIDGE_REFRESH_TOKEN";
+export declare const WORKSPACE_BRIDGE_DISABLED_ENV = "BORING_WORKSPACE_BRIDGE_DISABLED";
+export type BridgeCallerClass = "browser" | "runtime" | "server";
+export type BridgeActorKind = "human" | "agent" | "system" | "service";
+export interface BridgeRedactedActorRef {
+    /** Redacted, stable-enough label for logs/audit. Never a bearer token. */
+    label: string;
+    /** Optional non-secret stable id when the auth adapter has one. */
+    id?: string;
+}
+export interface BridgeActorAttribution {
+    actorKind: BridgeActorKind;
+    performedBy?: BridgeRedactedActorRef;
+    onBehalfOf?: BridgeRedactedActorRef;
+}
+export interface BridgeAuthContext {
+    callerClass: BridgeCallerClass;
+    workspaceId: string;
+    sessionId?: string;
+    pluginId?: string;
+    capabilities: readonly string[];
+    actor: BridgeActorAttribution;
+    tokenId?: string;
+    expiresAt?: string;
+}
+export type BridgeIdempotencyPolicy = "none" | "required" | "request-id";
+export interface WorkspaceBridgeOperationDefinition<TInput = unknown, TOutput = unknown> {
+    op: string;
+    version: number;
+    owner: string;
+    callerClassesAllowed: readonly BridgeCallerClass[];
+    requiredCapabilities: readonly string[];
+    /**
+     * Allow a caller authenticated for one workspace to invoke this operation on
+     * a registry owned by another workspace. Keep false/omitted for normal
+     * tenant-scoped operations; cross-workspace ops must perform their own
+     * explicit resource authorization.
+     */
+    allowCrossWorkspace?: boolean;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    timeoutMs: number;
+    maxInputBytes: number;
+    maxOutputBytes: number;
+    idempotencyPolicy: BridgeIdempotencyPolicy;
+    /** Type anchors only; no runtime value should be supplied. */
+    readonly __inputType?: TInput;
+    readonly __outputType?: TOutput;
+}
+export interface WorkspaceBridgeCallRequest<TInput = unknown> {
+    op: string;
+    input: TInput;
+    requestId?: string;
+    idempotencyKey?: string;
+}
+export interface WorkspaceBridgeCallSuccess<TOutput = unknown> {
+    ok: true;
+    op: string;
+    requestId: string;
+    output: TOutput;
+}
+export interface WorkspaceBridgeCallFailure {
+    ok: false;
+    op: string;
+    requestId?: string;
+    error: WorkspaceBridgeError;
+}
+export type WorkspaceBridgeCallResponse<TOutput = unknown> = WorkspaceBridgeCallSuccess<TOutput> | WorkspaceBridgeCallFailure;
+export declare enum WorkspaceBridgeErrorCode {
+    OpNotFound = "BRIDGE_OP_NOT_FOUND",
+    DuplicateOp = "BRIDGE_DUPLICATE_OP",
+    CallerNotAllowed = "BRIDGE_CALLER_NOT_ALLOWED",
+    AuthRequired = "BRIDGE_AUTH_REQUIRED",
+    CapabilityDenied = "BRIDGE_CAPABILITY_DENIED",
+    ResourceScopeDenied = "BRIDGE_RESOURCE_SCOPE_DENIED",
+    SchemaInvalid = "BRIDGE_SCHEMA_INVALID",
+    OutputSchemaInvalid = "BRIDGE_OUTPUT_SCHEMA_INVALID",
+    InputTooLarge = "BRIDGE_INPUT_TOO_LARGE",
+    OutputTooLarge = "BRIDGE_OUTPUT_TOO_LARGE",
+    Timeout = "BRIDGE_TIMEOUT",
+    HandlerFailed = "BRIDGE_HANDLER_FAILED",
+    IdempotencyRequired = "BRIDGE_IDEMPOTENCY_REQUIRED",
+    IdempotencyConflict = "BRIDGE_IDEMPOTENCY_CONFLICT",
+    ReplayRejected = "BRIDGE_REPLAY_REJECTED",
+    RateLimited = "BRIDGE_RATE_LIMITED",
+    InvalidToken = "BRIDGE_INVALID_TOKEN",
+    ExpiredToken = "BRIDGE_EXPIRED_TOKEN",
+    InvalidRequest = "BRIDGE_INVALID_REQUEST",
+    UnsupportedRuntime = "BRIDGE_UNSUPPORTED_RUNTIME"
+}
+export interface WorkspaceBridgeError {
+    code: WorkspaceBridgeErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare function createWorkspaceBridgeError(code: WorkspaceBridgeErrorCode, message: string, details?: Record<string, unknown>): WorkspaceBridgeError;
+export interface WorkspaceBridgeFileAssetPointer {
+    kind: "file-asset";
+    /** Workspace-relative path validated by the Workspace adapter/file route. */
+    path: string;
+    contentType: string;
+    byteLength?: number;
+    rawUrl?: string;
+}
+export type WorkspaceBridgeJsonValue = null | boolean | number | string | WorkspaceBridgeJsonValue[] | {
+    [key: string]: WorkspaceBridgeJsonValue;
+};

package/dist/{surface-aLQ_Hryw.d.ts → surface-h6IgrsK5.d.ts}

@@ -143,4 +143,4 @@ interface SurfaceResolverConfig extends SurfaceResolverMetadata {
 }
 type SurfaceResolverRegistration = Omit<SurfaceResolverConfig, "id">;
 
-export { type CommandConfig as C, type PaneProps as P, type SurfaceOpenRequest as S, WORKSPACE_OPEN_PATH_SURFACE_KIND as W, type PanelConfig as a, type PanelRegistration as b, type SurfacePanelResolution as c, type SurfaceResolverConfig as d, type SurfaceResolverRegistration as e, definePanel as f, type WorkspaceSourceProps as g, type SurfaceResolverExample as h, type WorkspaceSourceOpenPanelConfig as i };
+export { type CommandConfig as C, type PaneProps as P, type SurfaceResolverExample as S, type WorkspaceSourceProps as W, type PanelConfig as a, type SurfaceOpenRequest as b, type SurfacePanelResolution as c, WORKSPACE_OPEN_PATH_SURFACE_KIND as d, type WorkspaceSourceOpenPanelConfig as e, type PanelRegistration as f, type SurfaceResolverConfig as g, type SurfaceResolverRegistration as h, definePanel as i };

package/dist/testing-e2e.d.ts

@@ -1,73 +1,2 @@
-import { Page } from '@playwright/test';
-
-/**
- * Land on the app with a clean localStorage so persistence-sensitive tests
- * start from defaults. Pre-opens the workbench surface unless told
- * otherwise — see `openWorkbenchAtBoot`.
- *
- * Also drains the server-side bridge command queue. The bridge is process-
- * global on a shared dev server (E2E_EXTERNAL_SERVER=1); without an
- * explicit drain, a leftover command from a previous test (e.g. an
- * openPanel posted just before that test ended) gets re-delivered to the
- * next test's SSE subscriber and mounts an unexpected pane. The drain is
- * a no-op when the queue is already empty.
- */
-export declare function bootClean(page: Page, opts: BootCleanOptions): Promise<void>;
-
-export declare interface BootCleanOptions {
-    /**
-     * Storage prefix used by declarative chat shells. The
-     * bootClean default is to pre-seed `${shellKey}:surface=1` so the
-     * workbench mounts at boot — required for any test that posts an
-     * openPanel via the bridge (the dispatcher early-returns when no
-     * surface is mounted).
-     */
-    shellKey: string;
-    /** Extra localStorage entries to seed after the clear. */
-    seed?: Record<string, string>;
-    /**
-     * If false, surface=1 is NOT pre-seeded — the test starts with the
-     * workbench closed. Default: true.
-     */
-    openWorkbenchAtBoot?: boolean;
-    /** Vite + dockview cold-mount allowance. Default 2500ms. */
-    mountSettleMs?: number;
-}
-
-/**
- * Push an openPanel command through the workspace UI bridge, then poll
- * until the corresponding dockview tab actually appears. The chat shell
- * receives commands over an SSE stream; subscribe latency is
- * non-deterministic (cold Vite, ClickHouse warm-up, EventSource reconnect
- * budget), so we wait on the rendered tab rather than a fixed sleep.
- */
-export declare function openPaneViaBridge(page: Page, cfg: OpenPaneViaBridgeConfig): Promise<void>;
-
-export declare interface OpenPaneViaBridgeConfig {
-    /** Tab/panel instance id (e.g. `"chart:CPIAUCSL"`, `"deck:intro.md"`). */
-    id: string;
-    /** Registered panel component id. Must appear in `extraPanels`. */
-    component: string;
-    /** Tab title to wait for. */
-    title: string;
-    /** Forwarded to the panel component as its `params`. */
-    params: Record<string, unknown>;
-    /** Override the dockview-tab wait timeout. Default 10s. */
-    paneMountTimeoutMs?: number;
-}
-
-/**
- * Ensure the workbench surface is OPEN. Idempotent — checks the persisted
- * flag rather than blindly toggling, so it's safe to call after bootClean
- * (which pre-seeds the open flag by default) or independently.
- */
-export declare function openWorkbench(page: Page, opts: {
-    shellKey: string;
-}): Promise<void>;
-
-export { }
-
-
-declare global {
-    var __BORING_RUNTIME_SINGLETONS__: Record<string, unknown> | undefined;
-}
+export * from './src/front/testing/e2e.js'
+export {}