@get-bb/plugin-sdk 0.4.3

package/bundled-types/bb-plugin-sdk-internal-composer-customization-validation.d.ts

@@ -0,0 +1,30 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+import { ComposerCustomization, PluginComposerThreadRowStatus } from '@get-bb/plugin-sdk';
+
+declare const PLUGIN_SLOT_ID_PATTERN: RegExp;
+type RejectionReporter = (reason: string) => void;
+/**
+ * Parse the runtime value handed to
+ * `PluginContentScriptContext.experimental_setThreadRowStatus`. `undefined`
+ * means the value was rejected; `null` remains the explicit clear operation.
+ */
+declare function normalizePluginThreadRowStatus(value: unknown, onRejected: RejectionReporter): PluginComposerThreadRowStatus | null | undefined;
+declare function requireSlotId(kind: string, value: unknown): string;
+declare function requireMessageDirectiveId(kind: string, value: unknown): string;
+declare function requireNonEmptyString(kind: string, field: string, value: unknown): string;
+declare function requireOptionalString(kind: string, field: string, value: unknown): string | undefined;
+declare function requireComponent<T>(kind: string, value: unknown): T;
+declare function requireUniqueId(kind: string, seen: Set<string>, id: string): void;
+/**
+ * Validate one registration while isolating composer customization failures.
+ * The host and test harness inject their own rejection reporters.
+ */
+declare function collectComposerCustomization(registration: unknown, seenIds: Set<string>, onRejected: RejectionReporter): ComposerCustomization | null;
+
+export { PLUGIN_SLOT_ID_PATTERN, collectComposerCustomization, normalizePluginThreadRowStatus, requireComponent, requireMessageDirectiveId, requireNonEmptyString, requireOptionalString, requireSlotId, requireUniqueId };

package/bundled-types/bb-plugin-sdk-internal-composer-view.d.ts

@@ -0,0 +1,10 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+declare function isComposerDraftEmpty(text: string, attachmentCount: number): boolean;
+
+export { isComposerDraftEmpty };

package/bundled-types/bb-plugin-sdk-internal-host-policy.d.ts

@@ -0,0 +1,141 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+/**
+ * Core `bb` CLI top-level command names (plus commander's built-in help).
+ * Plugin CLI commands may not shadow these. Maintained by hand and checked
+ * against the real Commander program by
+ * apps/cli/src/__tests__/plugin-cli-proxy.test.ts.
+ *
+ * "automation" and "connect" are intentionally absent: builtin plugins own
+ * those top-level commands and the CLI proxies them.
+ */
+declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
+
+/**
+ * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
+ * Zod 4 schemas implement this interface directly; other validators can do
+ * the same without becoming part of BB's public protocol.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+type StandardSchemaV1Result<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaV1Issue[];
+};
+interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: PropertyKey | readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[];
+}
+interface PluginRpcMethodContract<InputSchema extends StandardSchemaV1 = StandardSchemaV1, OutputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly input: InputSchema;
+    readonly output: OutputSchema;
+}
+
+/**
+ * Declarative settings descriptors (`bb.settings.define`). Deliberately plain
+ * data — not zod — so the host can render settings forms and the CLI can
+ * parse values without executing plugin code.
+ */
+type PluginSettingDescriptor = {
+    type: "string";
+    label: string;
+    description?: string;
+    /** Stored in a 0600 file under <dataDir>/plugins/<id>/secrets/, never in the db or sent to the frontend. */
+    secret?: true;
+    default?: string;
+} | {
+    type: "boolean";
+    label: string;
+    description?: string;
+    default?: boolean;
+} | {
+    type: "select";
+    label: string;
+    description?: string;
+    options: string[];
+    default?: string;
+} | {
+    type: "project";
+    label: string;
+    description?: string;
+    default?: string;
+};
+type PluginSettingDescriptors = Record<string, PluginSettingDescriptor>;
+interface PluginCliOutputLimitError {
+    code: "plugin_cli_output_too_large";
+    message: string;
+    maxBytes: number;
+    stdoutBytes: number;
+    stderrBytes: number;
+    totalBytes: number;
+}
+/** Normalized host result returned by the plugin CLI HTTP/testing boundary. */
+interface PluginCliExecutionResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    error?: PluginCliOutputLimitError;
+}
+type PluginMentionTrigger = "@" | "#" | "$" | "!" | "~";
+
+/**
+ * Built-in dynamic tool names plugins may not shadow. Maintained by hand —
+ * kept in sync with the built-in tools in
+ * apps/server/src/services/threads/thread-runtime-config.ts by
+ * apps/server/test/services/plugins/plugin-agent-tools.test.ts.
+ */
+declare const RESERVED_AGENT_TOOL_NAMES: readonly string[];
+/** JSON values ≤256KB; larger writes are rejected with a clear error. */
+declare const KV_VALUE_MAX_BYTES: number;
+declare const PLUGIN_HTTP_METHODS: ReadonlySet<string>;
+declare const RPC_METHOD_PATTERN: RegExp;
+declare const BACKGROUND_NAME_PATTERN: RegExp;
+declare const CLI_COMMAND_NAME_PATTERN: RegExp;
+declare const AGENT_TOOL_NAME_PATTERN: RegExp;
+declare const PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS = 4096;
+/** Status labels ride on every tool-call event and share one timeline row. */
+declare const PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS = 80;
+declare const PLUGIN_AGENT_SELECTION_MAX_IDS = 256;
+declare const PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
+declare const PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES: number;
+declare const MENTION_PROVIDER_ID_PATTERN: RegExp;
+declare const SETTING_KEY_PATTERN: RegExp;
+/**
+ * Validate freeform descriptors from plugin code and merge them into the
+ * plugin's registered schema. Plugin source is not type-safe at runtime, so
+ * both the production and fake hosts must enforce this boundary identically.
+ */
+declare function registerSettingDescriptors(target: PluginSettingDescriptors, added: Record<string, unknown>): PluginSettingDescriptors;
+/** Validate a settings update. `null` means unset. */
+declare function validateSettingsUpdate(descriptors: PluginSettingDescriptors, values: Record<string, unknown>): string[];
+declare const PLUGIN_MENTION_TRIGGER_VALUES: readonly ["@", "#", "$", "!", "~"];
+declare function isPluginMentionTrigger(value: unknown): value is PluginMentionTrigger;
+declare function normalizeMentionProviderTriggers(providerId: string, triggers: unknown): readonly PluginMentionTrigger[];
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
+/** Duck-typed zod detection: plugin sources may carry their own zod copy,
+ * so instanceof is useless — anything with safeParse is treated as zod. */
+declare function isZodSchemaLike(value: unknown): boolean;
+/** Compact issue summary from a (possibly foreign-instance) zod error. */
+declare function summarizeParseIssues(error: unknown): string;
+declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResult, "error">, jsonOutput: boolean): PluginCliExecutionResult;
+
+export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SETTING_KEY_PATTERN, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validateSettingsUpdate };

package/bundled-types/bb-plugin-sdk-testing-app.d.ts

@@ -0,0 +1,238 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+import { ReactNode, ComponentType } from 'react';
+import { RenderResult } from '@testing-library/react';
+import { PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginContentScriptRegistration, PluginComposerScope, PluginComposerTextEffect, PluginComposerMention, PluginComposerThreadRowStatus, BbNavigate, PluginAppDefinition, PluginRpcContract, StandardSchemaV1InferInput, PluginRpcResult, PluginRealtimeConnectionState, PluginSidebarThreadsState, PluginSidebarPullRequest, PluginSidebarThreadActions } from '@get-bb/plugin-sdk';
+
+/**
+ * `@get-bb/plugin-sdk/testing/app` — the frontend plugin test harness. Tests a
+ * plugin's `app.tsx` source directly under vitest + jsdom, without the bb
+ * host or the esbuild bundle:
+ *
+ * - {@link installTestPluginRuntime} fills `globalThis.__bbPluginRuntime.
+ *   pluginSdkApp` with a test implementation of the `@get-bb/plugin-sdk/app`
+ *   surface (the same seam `bb plugin build` shims to the real app). It must
+ *   run BEFORE the plugin's `app.tsx` module evaluates, because that module
+ *   binds the runtime at import time — so import `app.tsx` through
+ *   {@link loadPluginApp}'s thunk form, or call the installer from a vitest
+ *   setup file when you prefer static imports.
+ * - {@link loadPluginApp} runs the definition's setup against a validating
+ *   collector (ported from the BB app's interpreter, same error messages)
+ *   and returns the typed slot registrations.
+ * - {@link renderSlot} mounts one registration's component with mock hook
+ *   backends: rpc as a method→handler map with a call log, realtime as a
+ *   channel you can push events into, settings/context as plain values, and
+ *   navigate/composer as recorders. Its `behavior`, `inspection`, and
+ *   `lifecycle` views separate host inputs, assertions, and mount controls;
+ *   the existing direct members remain aliases.
+ *
+ * Add `// @vitest-environment jsdom` to test files using renderSlot.
+ */
+interface RpcCall {
+    method: string;
+    input: unknown;
+}
+type NavigateCall = {
+    method: "toThread";
+    threadId: string;
+} | {
+    method: "toProject";
+    projectId: string;
+} | {
+    method: "toPluginPanel";
+    path: string;
+    options?: {
+        subPath?: string;
+        replace?: boolean;
+    };
+} | {
+    method: "toCompose";
+    options?: {
+        initialPrompt?: string;
+        focusPrompt?: boolean;
+    };
+} | {
+    method: "openThreadPanel";
+    options: Parameters<BbNavigate["openThreadPanel"]>[0];
+};
+interface ComposerLog {
+    /** Latest plain text in this isolated composer scope. */
+    readonly text: string;
+    /** Latest host-provided composer scope. */
+    readonly scope: PluginComposerScope;
+    /** Latest host-provided attachment count exposed through `useComposerView()`. */
+    readonly attachmentCount: number;
+    /** Latest host-rendered text effect requested by the plugin. */
+    textEffect: PluginComposerTextEffect | null;
+    textEffectCalls: Array<PluginComposerTextEffect | null>;
+    /** Whether this plugin currently holds the composer input lock. */
+    inputLocked: boolean;
+    inputLockCalls: boolean[];
+    quotes: string[];
+    mentions: PluginComposerMention[];
+    focusCount: number;
+}
+/** One recorded `experimental_useSidebarThreadActions()` call. */
+interface SidebarActionCall {
+    method: keyof PluginSidebarThreadActions;
+    threadId?: string;
+    options?: Record<string, unknown>;
+    title?: string;
+    pinned?: boolean;
+    read?: boolean;
+}
+/**
+ * Install the test runtime at `globalThis.__bbPluginRuntime.pluginSdkApp`.
+ * Idempotent per module instance; must run before the plugin's `app.tsx`
+ * (and therefore `@get-bb/plugin-sdk/app`) is imported.
+ */
+declare function installTestPluginRuntime(): void;
+interface CapturedPluginApp {
+    homepageSections: PluginHomepageSectionRegistration[];
+    settingsSections: PluginSettingsSectionRegistration[];
+    navPanels: PluginNavPanelRegistration[];
+    threadPanelActions: PluginThreadPanelActionRegistration[];
+    newThreadPanelActions: PluginNewThreadPanelActionRegistration[];
+    composerCustomizations: ComposerCustomization[];
+    pendingInteractions: PluginPendingInteractionRegistration[];
+    sidebarFooterActions: PluginSidebarFooterActionRegistration[];
+    threadLists: PluginThreadListRegistration[];
+    threadHeaderActions: PluginThreadHeaderActionRegistration[];
+    fileOpeners: PluginFileOpenerRegistration[];
+    messageDirectives: PluginMessageDirectiveRegistration[];
+    messageActions: PluginMessageActionRegistration[];
+    contentScripts: PluginContentScriptRegistration[];
+}
+type PluginAppModule = {
+    default: unknown;
+};
+type PluginAppSource = PluginAppDefinition | PluginAppModule | (() => Promise<PluginAppDefinition | PluginAppModule>);
+/**
+ * Install the test runtime, resolve the plugin app definition, and capture
+ * its slot registrations. Pass a thunk (`() => import("../app.tsx")`) so the
+ * plugin module evaluates after the runtime is installed — a static import
+ * would bind `definePluginApp` before the installer runs.
+ */
+declare function loadPluginApp(source: PluginAppSource): Promise<CapturedPluginApp>;
+interface ContentScriptTestMountOptions {
+    pluginId: string;
+    /** Defaults to 1. Pass the host generation you want the plugin to observe. */
+    generation?: number;
+    /**
+     * Simulate an older compatible host that predates the optional experimental
+     * thread-row status API. Current-host behavior is enabled by default.
+     */
+    omitExperimentalThreadRowStatus?: boolean;
+}
+interface ContentScriptThreadRowStatusCall {
+    threadId: string;
+    status: PluginComposerThreadRowStatus | null;
+}
+interface MountedPluginContentScripts {
+    inspection: {
+        readonly mountedIds: readonly string[];
+        readonly signal: AbortSignal;
+        readonly disposed: boolean;
+        readonly threadRowStatusCalls: readonly ContentScriptThreadRowStatusCall[];
+        getThreadRowStatus(threadId: string): PluginComposerThreadRowStatus | null;
+    };
+    lifecycle: {
+        /** Abort, then run returned cleanup functions once in reverse order. */
+        dispose(): Promise<void>;
+    };
+}
+/**
+ * Mount captured content scripts with host-faithful ordering and rollback.
+ * Call this once per simulated app window; each result owns an independent
+ * AbortSignal and cleanup lifecycle.
+ */
+declare function mountPluginContentScripts(app: CapturedPluginApp, options: ContentScriptTestMountOptions): Promise<MountedPluginContentScripts>;
+type PluginRpcTestHandlers<Contract extends PluginRpcContract> = {
+    [Method in keyof Contract]: (input: StandardSchemaV1InferInput<Contract[Method]["input"]>) => PluginRpcResult<Contract[Method]> | Promise<PluginRpcResult<Contract[Method]>>;
+};
+interface RenderSlotOptions<Contract extends PluginRpcContract = PluginRpcContract> {
+    /**
+     * Backing handlers for `useRpc().call`: method name → implementation.
+     * Inputs and results are JSON-round-tripped like the wire; a method
+     * without a handler rejects, and a throwing handler rejects with its
+     * message (what the real rpc client surfaces).
+     */
+    rpc?: PluginRpcTestHandlers<Contract>;
+    /** `useSettings()` values; omitted → `{ values: undefined, isLoading: false }`. */
+    settings?: Record<string, string | boolean>;
+    /** `useBbContext()` selection; both default to null. */
+    context?: {
+        projectId?: string | null;
+        threadId?: string | null;
+    };
+    /** Initial `useRealtimeConnectionState()` value; defaults to `connected`. */
+    realtimeConnectionState?: PluginRealtimeConnectionState;
+    /** Initial state for this render's isolated composer scope and view. */
+    composer?: {
+        text?: string;
+        scope?: PluginComposerScope;
+        attachmentCount?: number;
+    };
+    /**
+     * Threads and projects `experimental_useSidebarThreads()` reports. Omitted →
+     * a ready, empty list. Pass `{ status: "loading" }` to test that branch.
+     */
+    sidebarThreads?: Partial<PluginSidebarThreadsState>;
+    /**
+     * Pull requests `experimental_useSidebarThreadPullRequest()` reports, keyed
+     * by thread id. Omitted → every thread reports none.
+     */
+    sidebarPullRequests?: Record<string, PluginSidebarPullRequest>;
+    /** Host acceptance for `useBbNavigate().openThreadPanel`. */
+    openThreadPanel?: (options: Parameters<BbNavigate["openThreadPanel"]>[0]) => boolean;
+}
+/** Host-originated inputs a slot test can drive deterministically. */
+interface RenderedSlotBehaviorDrivers {
+    /**
+     * Push a realtime event to `useRealtime(channel, …)` subscribers, wrapped
+     * in act. The payload is JSON-round-tripped like `bb.realtime.publish`.
+     */
+    emitRealtime(channel: string, payload: unknown): Promise<void>;
+    /** Drive the lifecycle of the same connection used by realtime events. */
+    setRealtimeConnectionState(state: PluginRealtimeConnectionState): Promise<void>;
+    /** Replace composer text as a host-originated edit, wrapped in act. */
+    setComposerText(text: string): Promise<void>;
+    /** Replace the scope snapshots returned by composer hooks, wrapped in act. */
+    setComposerScope(scope: PluginComposerScope): Promise<void>;
+}
+/** Read-only call/write logs produced while the slot is mounted. */
+interface RenderedSlotInspectionState {
+    /** Every `useRpc().call`, in order. */
+    readonly rpcCalls: RpcCall[];
+    /** Every `useBbNavigate()` call, in order. */
+    readonly navigateCalls: NavigateCall[];
+    /** Every `experimental_useSidebarThreadActions()` call, in order. */
+    readonly sidebarActionCalls: SidebarActionCall[];
+    /** Everything written through `useComposer()`. */
+    readonly composer: ComposerLog;
+}
+/** Explicit mount controls, separate from behavior inputs and call logs. */
+interface RenderedSlotLifecycleControls {
+    rerender(ui: ReactNode): void;
+    unmount(): void;
+}
+/**
+ * Testing Library result plus BB-specific helpers. Direct members are
+ * retained for compatibility; named views make intent explicit in new tests.
+ */
+interface RenderedSlot extends RenderResult, RenderedSlotBehaviorDrivers, RenderedSlotInspectionState {
+    readonly behavior: RenderedSlotBehaviorDrivers;
+    readonly inspection: RenderedSlotInspectionState;
+    readonly lifecycle: RenderedSlotLifecycleControls;
+}
+declare function renderSlot<Props extends object, Contract extends PluginRpcContract = PluginRpcContract>(registration: {
+    component: ComponentType<Props>;
+}, props: Props, options?: RenderSlotOptions<Contract>): RenderedSlot;
+
+export { installTestPluginRuntime, loadPluginApp, mountPluginContentScripts, renderSlot };
+export type { CapturedPluginApp, ComposerLog, ContentScriptTestMountOptions, ContentScriptThreadRowStatusCall, MountedPluginContentScripts, NavigateCall, PluginAppSource, PluginRpcTestHandlers, RenderSlotOptions, RenderedSlot, RenderedSlotBehaviorDrivers, RenderedSlotInspectionState, RenderedSlotLifecycleControls, RpcCall, SidebarActionCall };