@get-bb/plugin-sdk 0.4.9 → 0.4.10

package/dist/testing/app.js

@@ -251,6 +251,137 @@ function collectComposerCustomization(registration, seenIds, onRejected) {
   }
 }
 
+// src/internal/file-navigation-validation.ts
+var FILE_PATH_MAX_LENGTH = 32768;
+var WINDOWS_DRIVE_ABSOLUTE_PATH = /^[A-Za-z]:[\\/]/u;
+var WINDOWS_UNC_ABSOLUTE_PATH = /^\\\\/u;
+function isJsonObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(value, keys) {
+  const actualKeys = Object.keys(value);
+  return actualKeys.length === keys.length && keys.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function isNonEmptyIdentity(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= FILE_PATH_MAX_LENGTH && value.trim() === value;
+}
+function hasControlCharacter(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint !== void 0 && codePoint < 32) return true;
+  }
+  return false;
+}
+function hasUnpairedSurrogate(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index);
+    if (codeUnit >= 55296 && codeUnit <= 56319) {
+      if (index + 1 >= value.length) return true;
+      const nextCodeUnit = value.charCodeAt(index + 1);
+      if (nextCodeUnit < 56320 || nextCodeUnit > 57343) return true;
+      index += 1;
+    } else if (codeUnit >= 56320 && codeUnit <= 57343) {
+      return true;
+    }
+  }
+  return false;
+}
+function isValidPathSegment(segment) {
+  return segment.length > 0 && segment !== "." && segment !== "..";
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isValidRelativeFilePath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > FILE_PATH_MAX_LENGTH || value.trim() !== value || value.includes("\\") || hasControlCharacter(value) || hasUnpairedSurrogate(value)) {
+    return false;
+  }
+  return value.split("/").every(isValidPathSegment);
+}
+function isValidAbsoluteHostFilePath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > FILE_PATH_MAX_LENGTH || value.trim() !== value || hasControlCharacter(value) || hasUnpairedSurrogate(value)) {
+    return false;
+  }
+  if (value.startsWith("/") && !value.startsWith("//")) {
+    const segments = value.slice(1).split("/");
+    return segments.length > 0 && segments.every(isValidPathSegment);
+  }
+  if (WINDOWS_DRIVE_ABSOLUTE_PATH.test(value)) {
+    const segments = value.slice(3).split(/[\\/]/u);
+    return segments.length > 0 && segments.every(isValidPathSegment);
+  }
+  if (WINDOWS_UNC_ABSOLUTE_PATH.test(value)) {
+    const segments = value.slice(2).split(/[\\/]/u);
+    return segments.length >= 3 && segments.every(isValidPathSegment);
+  }
+  return false;
+}
+function normalizeExperimentalLiveFileTarget(value) {
+  if (!isJsonObject(value) || typeof value.kind !== "string") return null;
+  switch (value.kind) {
+    case "workspace":
+      if (!hasExactKeys(value, ["kind", "environmentId", "path"]) || !isNonEmptyIdentity(value.environmentId) || !isValidRelativeFilePath(value.path)) {
+        return null;
+      }
+      return {
+        kind: value.kind,
+        environmentId: value.environmentId,
+        path: value.path
+      };
+    case "host":
+      if (!hasExactKeys(value, ["kind", "hostId", "path"]) || !isNonEmptyIdentity(value.hostId) || !isValidAbsoluteHostFilePath(value.path)) {
+        return null;
+      }
+      return { kind: value.kind, hostId: value.hostId, path: value.path };
+    case "thread-storage":
+      if (!hasExactKeys(value, ["kind", "threadId", "path"]) || !isNonEmptyIdentity(value.threadId) || !isValidRelativeFilePath(value.path)) {
+        return null;
+      }
+      return { kind: value.kind, threadId: value.threadId, path: value.path };
+    default:
+      return null;
+  }
+}
+function normalizeExperimentalFileLocation(value) {
+  if (value === null) return null;
+  if (!isJsonObject(value) || typeof value.kind !== "string") return void 0;
+  switch (value.kind) {
+    case "line":
+      if (!hasExactKeys(value, ["kind", "line", "column"]) || !isPositiveSafeInteger(value.line) || value.column !== null && !isPositiveSafeInteger(value.column)) {
+        return void 0;
+      }
+      return {
+        kind: value.kind,
+        line: value.line,
+        column: value.column
+      };
+    case "range":
+      if (!hasExactKeys(value, ["kind", "startLine", "endLine"]) || !isPositiveSafeInteger(value.startLine) || !isPositiveSafeInteger(value.endLine) || value.endLine < value.startLine) {
+        return void 0;
+      }
+      return {
+        kind: value.kind,
+        startLine: value.startLine,
+        endLine: value.endLine
+      };
+    default:
+      return void 0;
+  }
+}
+function normalizeExperimentalFileOpenOptions(value) {
+  if (!isJsonObject(value) || !hasExactKeys(value, ["target", "location"])) {
+    return null;
+  }
+  const target = normalizeExperimentalLiveFileTarget(value.target);
+  const location = normalizeExperimentalFileLocation(value.location);
+  if (target === null || location === void 0) return null;
+  return { target, location };
+}
+
 // src/internal/plugin-app-collector.ts
 function collectPluginAppRegistrations(definition, onComposerCustomizationRejected = (reason) => console.warn(reason)) {
   const collected = {
@@ -324,6 +455,7 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
         const kind = "slots.navPanel";
         const id = requireSlotId(kind, registration?.id);
         requireUniqueId(kind, seenIds.navPanel, id);
+        const panelId = id;
         const path = requireNonEmptyString(kind, "path", registration.path);
         if (!PLUGIN_SLOT_ID_PATTERN.test(path)) {
           throw new Error(
@@ -359,8 +491,25 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
                 `${fixedTabKind}: "layout" must be "padded" or "flush" when set`
               );
             }
+            const fixedTabPanelId = requireNonEmptyString(
+              fixedTabKind,
+              "panelId",
+              fixedTab?.panelId
+            );
+            if (fixedTabPanelId !== panelId) {
+              throw new Error(
+                `${fixedTabKind}: "panelId" must match its containing navPanel id ${JSON.stringify(panelId)}`
+              );
+            }
+            const experimentalTarget = fixedTab?.experimental_target;
+            if (experimentalTarget !== void 0 && (typeof experimentalTarget !== "object" || experimentalTarget === null || typeof Reflect.get(experimentalTarget, "validate") !== "function")) {
+              throw new Error(
+                `${fixedTabKind}: "experimental_target.validate" must be a function when set`
+              );
+            }
             return {
               id: id2,
+              panelId: fixedTabPanelId,
               title: requireNonEmptyString(
                 fixedTabKind,
                 "title",
@@ -372,7 +521,10 @@ function collectPluginAppRegistrations(definition, onComposerCustomizationReject
                 fixedTab?.icon
               ),
               component: requireComponent(fixedTabKind, fixedTab?.component),
-              ...layout === void 0 ? {} : { layout }
+              ...layout === void 0 ? {} : { layout },
+              ...experimentalTarget === void 0 ? {} : {
+                experimental_target: experimentalTarget
+              }
             };
           });
         })();
@@ -679,6 +831,65 @@ function TestThreadChat({
 function TestMarkdown({ content, className }) {
   return /* @__PURE__ */ jsx("div", { "data-testid": "bb-markdown", className, children: content });
 }
+function TestUrlLink({
+  href,
+  onClick,
+  rel,
+  target,
+  ...anchorProps
+}) {
+  const navigate = useSlotEnv("experimental_UrlLink").navigate;
+  const normalizedTarget = target?.toLowerCase();
+  const opensNewBrowsingContext = normalizedTarget !== void 0 && normalizedTarget !== "" && normalizedTarget !== "_self" && normalizedTarget !== "_parent" && normalizedTarget !== "_top" && normalizedTarget !== "_unfencedtop";
+  const relTokens = rel?.split(/\s+/u).filter(Boolean) ?? [];
+  const normalizedRelTokens = relTokens.map((token) => token.toLowerCase());
+  const resolvedRel = opensNewBrowsingContext && !normalizedRelTokens.includes("opener") ? [
+    ...relTokens,
+    ...normalizedRelTokens.includes("noopener") ? [] : ["noopener"],
+    ...normalizedRelTokens.includes("noreferrer") ? [] : ["noreferrer"]
+  ].join(" ") : rel;
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ...anchorProps,
+      href,
+      target,
+      rel: resolvedRel,
+      onClick: (event) => {
+        onClick?.(event);
+        if (event.defaultPrevented || event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.currentTarget.hasAttribute("download") || event.currentTarget.hasAttribute("target")) {
+          return;
+        }
+        if (navigate.experimental_openUrl(href)) event.preventDefault();
+      }
+    }
+  );
+}
+function TestFileLink({
+  target,
+  location = null,
+  onClick,
+  ...anchorProps
+}) {
+  const navigate = useSlotEnv("experimental_FileLink").navigate;
+  const options = normalizeExperimentalFileOpenOptions({ target, location });
+  const href = options === null ? void 0 : `./${encodeURIComponent(options.target.path)}`;
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ...anchorProps,
+      href,
+      onClick: (event) => {
+        onClick?.(event);
+        if (options === null || event.defaultPrevented || event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.currentTarget.hasAttribute("download")) {
+          return;
+        }
+        event.preventDefault();
+        navigate.experimental_openFilePreview(options);
+      }
+    }
+  );
+}
 function TestNewThreadComposer({
   defaultProjectId,
   defaultProviderId,
@@ -829,6 +1040,30 @@ var testPluginSdkApp = {
   useBbNavigate() {
     return useSlotEnv("useBbNavigate").navigate;
   },
+  experimental_useAppPanel() {
+    return useSlotEnv("experimental_useAppPanel").appPanel;
+  },
+  experimental_useFixedTabTarget(tab) {
+    const store = useSlotEnv("experimental_useFixedTabTarget").fixedTabTarget;
+    const state = useSyncExternalStore(
+      store.subscribe,
+      store.getSnapshot,
+      store.getSnapshot
+    );
+    if (state === null || state.panelId !== tab.panelId || state.tabId !== tab.id || tab.experimental_target === void 0) {
+      return null;
+    }
+    try {
+      if (!tab.experimental_target.validate(state.target)) return null;
+    } catch {
+      return null;
+    }
+    return {
+      clear: () => store.clear(state.sequence),
+      sequence: state.sequence,
+      target: state.target
+    };
+  },
   useComposer() {
     const composer = useSlotEnv("useComposer").composer;
     const version = useSyncExternalStore(
@@ -847,6 +1082,8 @@ var testPluginSdkApp = {
   },
   ThreadChat: TestThreadChat,
   Markdown: TestMarkdown,
+  experimental_FileLink: TestFileLink,
+  experimental_UrlLink: TestUrlLink,
   experimental_NewThreadComposer: TestNewThreadComposer,
   experimental_SourceCode: TestSourceCode,
   experimental_Diff: TestDiff,
@@ -1086,6 +1323,70 @@ function renderSlot(registration, props, options = {}) {
     }
   };
   const navigateCalls = [];
+  const experimental_fixedTabOpenCalls = [];
+  let fixedTabTargetSnapshot = options.experimental_fixedTabTarget === void 0 ? null : {
+    panelId: options.experimental_fixedTabTarget.panelId,
+    sequence: 1,
+    tabId: options.experimental_fixedTabTarget.tabId,
+    target: strictJsonRoundTrip(
+      options.experimental_fixedTabTarget.target,
+      "fixed tab target"
+    )
+  };
+  const fixedTabTargetListeners = /* @__PURE__ */ new Set();
+  const fixedTabTarget = {
+    getSnapshot: () => fixedTabTargetSnapshot,
+    subscribe(listener) {
+      fixedTabTargetListeners.add(listener);
+      return () => fixedTabTargetListeners.delete(listener);
+    },
+    clear(sequence) {
+      if (fixedTabTargetSnapshot?.sequence !== sequence) return;
+      fixedTabTargetSnapshot = null;
+      for (const listener of fixedTabTargetListeners) listener();
+    }
+  };
+  const appPanel = {
+    openFixedTab(panelOptions) {
+      let target;
+      if (panelOptions.target !== void 0) {
+        try {
+          target = strictJsonRoundTrip(
+            panelOptions.target,
+            "fixed tab open target"
+          );
+        } catch {
+          return false;
+        }
+        if (panelOptions.tab.experimental_target === void 0) return false;
+        try {
+          if (!panelOptions.tab.experimental_target.validate(target)) {
+            return false;
+          }
+        } catch {
+          return false;
+        }
+      }
+      const call = {
+        surface: panelOptions.surface,
+        panelId: panelOptions.tab.panelId,
+        tabId: panelOptions.tab.id,
+        ...target === void 0 ? {} : { target }
+      };
+      experimental_fixedTabOpenCalls.push(call);
+      const accepted = options.experimental_openFixedTab?.(call) ?? false;
+      if (accepted && target !== void 0) {
+        fixedTabTargetSnapshot = {
+          panelId: panelOptions.tab.panelId,
+          sequence: (fixedTabTargetSnapshot?.sequence ?? 0) + 1,
+          tabId: panelOptions.tab.id,
+          target
+        };
+        for (const listener of fixedTabTargetListeners) listener();
+      }
+      return accepted;
+    }
+  };
   const sidebarActionCalls = [];
   const sidebarPullRequests = new Map(
     Object.entries(options.sidebarPullRequests ?? {})
@@ -1151,6 +1452,24 @@ function renderSlot(registration, props, options = {}) {
         options: panelOptions
       });
       return options.openThreadPanel?.(panelOptions) ?? false;
+    },
+    experimental_openUrl(url) {
+      navigateCalls.push({ method: "experimental_openUrl", url });
+      return options.openUrl?.(url) ?? false;
+    },
+    experimental_openFilePreview(fileOptions) {
+      navigateCalls.push({
+        method: "experimental_openFilePreview",
+        options: fileOptions
+      });
+      return options.openFilePreview?.(fileOptions) ?? false;
+    },
+    experimental_openFileExternally(fileOptions) {
+      navigateCalls.push({
+        method: "experimental_openFileExternally",
+        options: fileOptions
+      });
+      return options.openFileExternally?.(fileOptions) ?? false;
     }
   };
   const projectId = options.context?.projectId ?? null;
@@ -1252,6 +1571,9 @@ ${block}
     bbContext: { projectId, threadId },
     navigate,
     navigateCalls,
+    appPanel,
+    experimental_fixedTabOpenCalls,
+    fixedTabTarget,
     composer,
     composerLog,
     sidebarThreads,
@@ -1307,6 +1629,7 @@ ${block}
     setComposerText,
     setComposerScope,
     navigateCalls,
+    experimental_fixedTabOpenCalls,
     sidebarActionCalls,
     composer: composerLog,
     behavior: {
@@ -1318,6 +1641,7 @@ ${block}
     inspection: {
       rpcCalls,
       navigateCalls,
+      experimental_fixedTabOpenCalls,
       sidebarActionCalls,
       composer: composerLog
     },

package/dist/testing/index.js

@@ -66,6 +66,7 @@ var PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
 var PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES = 128 * 1024;
 var MENTION_PROVIDER_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+var PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES = 64 * 1024;
 var SETTING_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var settingsBaseFields = {
   label: z2.string().min(1),
@@ -267,6 +268,70 @@ function validateProviderLiteralArray(args) {
   }
   return Object.freeze(normalized);
 }
+function normalizeProviderBridgeOptions(providerId, value) {
+  const active = /* @__PURE__ */ new Set();
+  function visit(current, path) {
+    if (current === null || typeof current === "string" || typeof current === "boolean") {
+      return current;
+    }
+    if (typeof current === "number") {
+      if (!Number.isFinite(current)) {
+        throw new Error(
+          `provider "${providerId}" experimental_bridgeOptions${path} must be finite JSON`
+        );
+      }
+      return current;
+    }
+    if (typeof current !== "object") {
+      throw new Error(
+        `provider "${providerId}" experimental_bridgeOptions${path} must be JSON`
+      );
+    }
+    if (active.has(current)) {
+      throw new Error(
+        `provider "${providerId}" experimental_bridgeOptions must not contain cycles`
+      );
+    }
+    active.add(current);
+    try {
+      if (Array.isArray(current)) {
+        const normalized3 = current.map(
+          (entry, index) => visit(entry, `${path}[${index}]`)
+        );
+        Object.freeze(normalized3);
+        return normalized3;
+      }
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(
+          `provider "${providerId}" experimental_bridgeOptions${path} must contain only plain JSON objects`
+        );
+      }
+      const normalized2 = Object.fromEntries(
+        Object.entries(current).map(([key, entry]) => [
+          key,
+          visit(entry, `${path}.${key}`)
+        ])
+      );
+      Object.freeze(normalized2);
+      return normalized2;
+    } finally {
+      active.delete(current);
+    }
+  }
+  const normalized = visit(value, "");
+  if (normalized === null || Array.isArray(normalized) || typeof normalized !== "object") {
+    throw new Error(
+      `provider "${providerId}" experimental_bridgeOptions must be an object`
+    );
+  }
+  if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES) {
+    throw new Error(
+      `provider "${providerId}" experimental_bridgeOptions exceeds ${PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES} bytes`
+    );
+  }
+  return normalized;
+}
 function validatePluginProviderDeclaration(declaration) {
   if (typeof declaration !== "object" || declaration === null) {
     throw new Error("provider declaration must be an object");
@@ -304,6 +369,24 @@ function validatePluginProviderDeclaration(declaration) {
   if (typeof capabilities !== "object" || capabilities === null) {
     throw new Error(`provider "${id}" capabilities must be an object`);
   }
+  const experimentalProviderHealth = capabilities.experimental_providerHealth ?? false;
+  const experimentalProviderUsage = capabilities.experimental_providerUsage ?? false;
+  const experimentalProviderInstallation = capabilities.experimental_providerInstallation ?? false;
+  if (typeof experimentalProviderHealth !== "boolean") {
+    throw new Error(
+      `provider "${id}" capabilities.experimental_providerHealth must be a boolean`
+    );
+  }
+  if (typeof experimentalProviderUsage !== "boolean") {
+    throw new Error(
+      `provider "${id}" capabilities.experimental_providerUsage must be a boolean`
+    );
+  }
+  if (typeof experimentalProviderInstallation !== "boolean") {
+    throw new Error(
+      `provider "${id}" capabilities.experimental_providerInstallation must be a boolean`
+    );
+  }
   const booleanCapabilityFields = [
     "supportsServiceTier",
     "supportsNativeUserQuestion",
@@ -325,6 +408,9 @@ function validatePluginProviderDeclaration(declaration) {
     );
   }
   const normalizedCapabilities = Object.freeze({
+    experimental_providerHealth: experimentalProviderHealth,
+    experimental_providerUsage: experimentalProviderUsage,
+    experimental_providerInstallation: experimentalProviderInstallation,
     supportsServiceTier: capabilities.supportsServiceTier,
     supportsNativeUserQuestion: capabilities.supportsNativeUserQuestion,
     fork: capabilities.fork,
@@ -354,10 +440,27 @@ function validatePluginProviderDeclaration(declaration) {
     allowed: PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES,
     requireNonEmpty: false
   });
+  const bridgeOptions = declaration.experimental_bridgeOptions === void 0 ? void 0 : normalizeProviderBridgeOptions(
+    id,
+    declaration.experimental_bridgeOptions
+  );
+  const visibility = declaration.experimental_visibility ?? "always";
+  if (visibility !== "always" && visibility !== "installed") {
+    throw new Error(
+      `provider "${id}" experimental_visibility must be "always" or "installed"`
+    );
+  }
+  if (visibility === "installed" && !normalizedCapabilities.experimental_providerHealth) {
+    throw new Error(
+      `provider "${id}" experimental_visibility "installed" requires experimental_providerHealth`
+    );
+  }
   return Object.freeze({
     id,
     displayName,
     ...icon === void 0 ? {} : { icon },
+    ...bridgeOptions === void 0 ? {} : { experimental_bridgeOptions: bridgeOptions },
+    experimental_visibility: visibility,
     capabilities: normalizedCapabilities,
     composerActions
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-bb/plugin-sdk",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "homepage": "https://github.com/get-bb/bb#readme",
   "bugs": {
     "url": "https://github.com/get-bb/bb/issues"
@@ -56,6 +56,12 @@
       "import": "./dist/internal/composer-view.js",
       "default": "./dist/internal/composer-view.js"
     },
+    "./internal/file-navigation-validation": {
+      "source": "./src/internal/file-navigation-validation.ts",
+      "types": "./bundled-types/bb-plugin-sdk-internal-file-navigation-validation.d.ts",
+      "import": "./dist/internal/file-navigation-validation.js",
+      "default": "./dist/internal/file-navigation-validation.js"
+    },
     "./internal/host-policy": {
       "source": "./src/internal/host-policy.ts",
       "types": "./bundled-types/bb-plugin-sdk-internal-host-policy.d.ts",