mindoodb-app-sdk 0.0.70 → 0.0.72

package/dist/testing/index.js

@@ -1,10 +1,19 @@
 import {
   MINDOODB_APP_VALUE_TAG,
+  MindooDBAppEmbedValidationError,
   assertValidMindooDBCreateIds,
   mindooDBAppComponentFieldsMatch,
+  mindooDBAppComponentSupports,
+  normalizeMindooDBAppInspectAnchor,
+  normalizeMindooDBAppInspectRequest,
+  normalizeMindooDBAppInspection,
+  normalizeMindooDBAppIssues,
   pageUsers,
-  releaseMindooDBAppBridgeSessions
-} from "../chunk-P7SOHCEQ.js";
+  performMindooDBAppEmbeddingSave,
+  releaseMindooDBAppBridgeSessions,
+  resolveMindooDBAppEmbedValidation,
+  validateMindooDBAppDefinition
+} from "../chunk-UFP7O4OJ.js";
 
 // src/testing/index.ts
 import * as Automerge from "@automerge/automerge";
@@ -469,6 +478,13 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
   let nextSaveError = null;
   let embeddingDirty;
   let saveRequestHandler = null;
+  let inspectionProvider = null;
+  let showIssuesHandler = null;
+  let revealHandler = null;
+  const embeddingValidations = [];
+  let embeddingSaveCount = 0;
+  const beforeSaveHandlers = /* @__PURE__ */ new Map();
+  const savedListeners = /* @__PURE__ */ new Set();
   let embedCounter = 0;
   let embeddingFinish = null;
   const accessRequests = [];
@@ -529,7 +545,10 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
       rect: mockRect(input),
       visible: input.visible !== false,
       active: false,
-      agentTools: null
+      agentTools: null,
+      supports: [...component.supports ?? []],
+      beforeSave: null,
+      requests: []
     });
     setActive(embedId);
     return embedId;
@@ -582,6 +601,7 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
     handles.get(embedId)?.settle(event);
     handles.delete(embedId);
     toolNames.delete(embedId);
+    beforeSaveHandlers.delete(embedId);
     closedListeners.forEach((listener) => listener(event));
     notifyChange();
   }
@@ -604,6 +624,40 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
     closed;
     dirty = void 0;
     dirtyListeners = /* @__PURE__ */ new Set();
+    savedListeners = /* @__PURE__ */ new Set();
+    get supports() {
+      return embeds.get(this.embedId)?.supports ?? [];
+    }
+    async inspect(request) {
+      return await inspectEmbed(this.embedId, request);
+    }
+    onBeforeSave(handler, options2) {
+      setBeforeSave(this.embedId, handler, options2?.inspect);
+      return () => {
+        if (beforeSaveHandlers.get(this.embedId) === handler) {
+          setBeforeSave(this.embedId, null);
+        }
+      };
+    }
+    onAfterSave(listener) {
+      this.savedListeners.add(listener);
+      return () => {
+        this.savedListeners.delete(listener);
+      };
+    }
+    notifySaved() {
+      const event = { embedId: this.embedId };
+      this.savedListeners.forEach((listener) => listener(event));
+    }
+    async showIssues(issues) {
+      await showEmbedIssues(this.embedId, issues);
+    }
+    async reveal(anchor) {
+      await revealInEmbed(this.embedId, anchor);
+    }
+    async callTool(name, input) {
+      return await callEmbedTool(this.embedId, name, input ?? {});
+    }
     onDirtyChange(listener) {
       this.dirtyListeners.add(listener);
       return () => {
@@ -703,7 +757,8 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
     notifyChange();
   }
   async function saveEmbed(embedId) {
-    if (!embeds.has(embedId)) {
+    const entry = embeds.get(embedId);
+    if (!entry) {
       throw new Error("Unknown embed.");
     }
     const error = nextSaveError;
@@ -711,7 +766,117 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
     if (error) {
       throw new Error(error);
     }
+    if (mindooDBAppComponentSupports(entry.supports, "validate")) {
+      const validation = await validateEmbed(embedId);
+      if (!validation.ok) {
+        throw new MindooDBAppEmbedValidationError(validation.issues);
+      }
+    }
     setEmbedDirty(embedId, false);
+    notifyEmbedSaved(embedId);
+  }
+  function entryOf(embedId) {
+    const entry = embeds.get(embedId);
+    if (!entry) {
+      throw new Error("Unknown embed.");
+    }
+    return entry;
+  }
+  function unsupported(message) {
+    return Object.assign(new Error(message), { name: "unsupported" });
+  }
+  async function inspectEmbed(embedId, request) {
+    const entry = entryOf(embedId);
+    const inspect = normalizeMindooDBAppInspectRequest(request);
+    entry.requests.push({ request: "inspect", inspect });
+    if (!options.embedInspection || !mindooDBAppComponentSupports(entry.supports, "inspect")) {
+      throw unsupported("The component cannot describe its document.");
+    }
+    return normalizeMindooDBAppInspection(await options.embedInspection(structuredClone(entry), inspect));
+  }
+  function setBeforeSave(embedId, handler, inspect) {
+    const entry = entryOf(embedId);
+    if (handler) {
+      beforeSaveHandlers.set(embedId, handler);
+      entry.beforeSave = { inspect: normalizeMindooDBAppInspectRequest(inspect) };
+    } else {
+      beforeSaveHandlers.delete(embedId);
+      entry.beforeSave = null;
+    }
+    notifyChange();
+  }
+  async function validateEmbed(embedId, validateOptions = {}) {
+    const entry = entryOf(embedId);
+    const handler = beforeSaveHandlers.get(embedId);
+    if (!handler) {
+      return { ok: true, issues: [] };
+    }
+    let inspection = null;
+    if (options.embedInspection && mindooDBAppComponentSupports(entry.supports, "inspect")) {
+      inspection = normalizeMindooDBAppInspection(
+        await options.embedInspection(structuredClone(entry), entry.beforeSave?.inspect ?? {})
+      );
+    }
+    const root = await getDatabase(entry.databaseId).documents.get(entry.docId);
+    const answer = await handler({
+      embedId,
+      inspection,
+      root: root ? JSON.parse(JSON.stringify(root.data)) : null
+    });
+    return await resolveMindooDBAppEmbedValidation(
+      normalizeMindooDBAppIssues(answer?.issues),
+      validateOptions.interactive !== false,
+      options.confirmSaveWarnings ?? (() => true)
+    );
+  }
+  function notifyEmbedSaved(embedId) {
+    if (!embeds.has(embedId)) {
+      return;
+    }
+    handles.get(embedId)?.notifySaved();
+    savedListeners.forEach((listener) => listener({ embedId }));
+  }
+  async function showEmbedIssues(embedId, issues) {
+    const entry = entryOf(embedId);
+    entry.requests.push({ request: "showIssues", issues: normalizeMindooDBAppIssues(issues) });
+    if (!mindooDBAppComponentSupports(entry.supports, "issues")) {
+      throw unsupported("The component cannot show issues.");
+    }
+  }
+  async function revealInEmbed(embedId, anchor) {
+    const entry = entryOf(embedId);
+    const normalized = normalizeMindooDBAppInspectAnchor(anchor);
+    if (!normalized) {
+      throw new Error("Invalid anchor.");
+    }
+    entry.requests.push({ request: "reveal", anchor: normalized });
+    if (!mindooDBAppComponentSupports(entry.supports, "reveal")) {
+      throw unsupported("The component cannot reveal places.");
+    }
+  }
+  async function callEmbedTool(embedId, name, input) {
+    const entry = entryOf(embedId);
+    const prefix = `${toolPrefix(entry.component)}_`;
+    const bare = name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    entry.requests.push({ request: "callTool", name: bare, input: structuredClone(input) });
+    if (!options.embedTools) {
+      throw unsupported(`The component has no tool "${bare}".`);
+    }
+    return structuredClone(await options.embedTools(structuredClone(entry), bare, structuredClone(input)));
+  }
+  async function validateEmbedding(validateOptions = {}) {
+    const interactive = validateOptions.interactive !== false;
+    const raw = await options.embeddingValidation?.({ interactive }) ?? { ok: true, issues: [] };
+    const result = {
+      ok: raw.ok !== false,
+      issues: normalizeMindooDBAppIssues(raw.issues),
+      ...raw.timedOut ? { timedOut: true } : {}
+    };
+    embeddingValidations.push({ interactive, result: structuredClone(result) });
+    return result;
+  }
+  function unsupportedHandler() {
+    throw unsupported("unsupported");
   }
   function setVisible(embedId, visible) {
     const entry = embeds.get(embedId);
@@ -723,7 +888,7 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
   return {
     components: {
       async list(query) {
-        return components.filter((entry) => !query?.intent || entry.intents.includes(query.intent)).filter((entry) => !query?.document || mindooDBAppComponentFieldsMatch(entry.match, query.document)).map((entry) => structuredClone(entry));
+        return components.filter((entry) => !query?.intent || entry.intents.includes(query.intent)).filter((entry) => (query?.requires ?? []).every((requirement) => mindooDBAppComponentSupports(entry.supports, requirement))).filter((entry) => !query?.document || mindooDBAppComponentFieldsMatch(entry.match, query.document)).map((entry) => structuredClone(entry));
       }
     },
     embeds: {
@@ -758,6 +923,36 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
             saveRequestHandler = null;
           }
         };
+      },
+      provideInspection(provider) {
+        inspectionProvider = provider;
+        return () => {
+          if (inspectionProvider === provider) inspectionProvider = null;
+        };
+      },
+      onShowIssues(handler) {
+        showIssuesHandler = handler;
+        return () => {
+          if (showIssuesHandler === handler) showIssuesHandler = null;
+        };
+      },
+      onReveal(handler) {
+        revealHandler = handler;
+        return () => {
+          if (revealHandler === handler) revealHandler = null;
+        };
+      },
+      validate: validateEmbedding,
+      async save(flush, saveOptions) {
+        return await performMindooDBAppEmbeddingSave({
+          validate: () => validateEmbedding(saveOptions),
+          provider: inspectionProvider,
+          showIssues: showIssuesHandler,
+          flush,
+          saved: () => {
+            embeddingSaveCount += 1;
+          }
+        });
       }
     },
     openEmbed,
@@ -821,6 +1016,44 @@ function createMockEmbedHost(options, getDatabase, listDatabaseIds = () => []) {
     },
     setSaveRequestHandler(handler) {
       saveRequestHandler = handler;
+    },
+    inspectEmbed,
+    setBeforeSave,
+    validateEmbed,
+    notifyEmbedSaved,
+    onSaved(listener) {
+      savedListeners.add(listener);
+      return () => {
+        savedListeners.delete(listener);
+      };
+    },
+    showEmbedIssues,
+    revealInEmbed,
+    callEmbedTool,
+    getEmbedRequests(embedId) {
+      return structuredClone(embeds.get(embedId)?.requests ?? []);
+    },
+    async requestEmbeddingInspection(request) {
+      if (!inspectionProvider) unsupportedHandler();
+      return normalizeMindooDBAppInspection(await inspectionProvider(normalizeMindooDBAppInspectRequest(request)));
+    },
+    async requestEmbeddingShowIssues(issues) {
+      if (!showIssuesHandler) unsupportedHandler();
+      await showIssuesHandler(normalizeMindooDBAppIssues(issues));
+    },
+    async requestEmbeddingReveal(anchor) {
+      if (!revealHandler) unsupportedHandler();
+      await revealHandler(anchor);
+    },
+    getEmbeddingValidations() {
+      return structuredClone(embeddingValidations);
+    },
+    getEmbeddingSaveCount() {
+      return embeddingSaveCount;
+    },
+    validateEmbedding,
+    recordEmbeddingSaved() {
+      embeddingSaveCount += 1;
     }
   };
 }
@@ -2383,6 +2616,84 @@ Allow?`),
   return testHost;
 }
 
+// src/testing/agentManifest.ts
+function localeKeys(map) {
+  return map ? Object.keys(map).sort().join(",") : "";
+}
+function findGuideProblems(name, text, prefix, registered, ignore) {
+  const problems = /* @__PURE__ */ new Set();
+  const prefixed = new RegExp(`(?<![A-Za-z0-9_])${prefix}_([a-z0-9_]+)(?![A-Za-z0-9_*<])`, "g");
+  for (const match of text.matchAll(prefixed)) {
+    const full = match[0];
+    const bare = match[1].replace(/_+$/, "");
+    if (!bare || ignore.has(full) || ignore.has(bare) || registered.has(bare)) continue;
+    problems.add(`${name} names \`${full}\`, which the app does not register.`);
+  }
+  const families = new Set([...registered].filter((tool) => tool.includes("_")).map((tool) => tool.split("_")[0]));
+  for (const match of text.matchAll(/`([a-z][a-z0-9]*_[a-z0-9_]*[a-z0-9])(?:\(\))?`/g)) {
+    const bare = match[1];
+    if (bare.startsWith("haven_") || bare.startsWith(`${prefix}_`)) continue;
+    if (registered.has(bare) || ignore.has(bare) || !families.has(bare.split("_")[0])) continue;
+    problems.add(`${name} names \`${bare}\`, which looks like a tool but the app does not register it.`);
+  }
+  return [...problems];
+}
+function checkAgentManifest(options) {
+  const errors = [];
+  const warnings = [];
+  const validation = validateMindooDBAppDefinition(options.definition);
+  errors.push(...validation.errors);
+  const definition = validation.definition;
+  if (!definition) {
+    return { errors, warnings };
+  }
+  const agent = definition.agent;
+  if (!agent) {
+    errors.push("haven-app.json has no agent block.");
+    return { errors, warnings };
+  }
+  const prefix = options.toolPrefix ?? mockAgentToolPrefix(definition.appId, definition.agentToolPrefix);
+  const registered = new Set(options.tools.map((tool) => typeof tool === "string" ? tool : tool.name));
+  const ignore = new Set(options.ignore ?? []);
+  const covered = /* @__PURE__ */ new Set();
+  for (const capability of agent.capabilities) {
+    for (const tool of capability.tools) {
+      covered.add(tool);
+      if (!registered.has(tool)) {
+        const hint = tool.startsWith(`${prefix}_`) ? " Name it without the prefix." : "";
+        errors.push(`Capability "${capability.id}" names the tool "${tool}", which the app does not register.${hint}`);
+      }
+    }
+  }
+  const internal = new Set(options.internalTools ?? []);
+  for (const tool of registered) {
+    if (!covered.has(tool) && !internal.has(tool)) {
+      warnings.push(`The tool "${tool}" belongs to no capability.`);
+    }
+  }
+  const summaryLocales = localeKeys(agent.summary);
+  const mismatched = [
+    ...agent.capabilities.map((capability) => [`capability "${capability.id}" title`, localeKeys(capability.title)]),
+    ...agent.examples ? [["examples", localeKeys(agent.examples)]] : []
+  ].filter(([, locales]) => locales !== summaryLocales);
+  for (const [what, locales] of mismatched) {
+    errors.push(`The agent ${what} has the locales ${locales || "(none)"}, the summary ${summaryLocales}.`);
+  }
+  const texts = Array.isArray(options.guideTexts) ? options.guideTexts.map((text, index) => [`guide text #${index}`, text]) : Object.entries(options.guideTexts ?? {});
+  for (const [name, text] of texts) {
+    errors.push(...findGuideProblems(name, text, prefix, registered, ignore));
+  }
+  return { errors, warnings };
+}
+function assertAgentManifest(options) {
+  const { errors, warnings } = checkAgentManifest(options);
+  if (errors.length) {
+    throw new Error(`The agent profile does not match the app's tools:
+- ${errors.join("\n- ")}`);
+  }
+  return warnings;
+}
+
 // src/testing/index.ts
 var PROTOCOL = "mindoodb-app-bridge";
 var MOCK_SIGNING_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAmockmockmockmockmockmockmockmockmockmockmoc=\n-----END PUBLIC KEY-----\n";
@@ -5951,7 +6262,15 @@ function createMockMindooDBAppSession(options = {}) {
     setEmbedAgentTools: (embedId, names, toolOptions) => state.embedHost.setEmbedAgentTools(embedId, names, toolOptions),
     failNextEmbedSave: (message) => state.embedHost.failNextSave(message),
     getEmbeddingDirty: () => state.embedHost.getEmbeddingDirty(),
-    requestEmbeddingSave: () => state.embedHost.requestEmbeddingSave()
+    requestEmbeddingSave: () => state.embedHost.requestEmbeddingSave(),
+    validateEmbed: (embedId, validateOptions) => state.embedHost.validateEmbed(embedId, validateOptions),
+    notifyEmbedSaved: (embedId) => state.embedHost.notifyEmbedSaved(embedId),
+    getEmbedRequests: (embedId) => state.embedHost.getEmbedRequests(embedId),
+    requestEmbeddingInspection: (request) => state.embedHost.requestEmbeddingInspection(request),
+    requestEmbeddingShowIssues: (issues) => state.embedHost.requestEmbeddingShowIssues(issues),
+    requestEmbeddingReveal: (anchor) => state.embedHost.requestEmbeddingReveal(anchor),
+    getEmbeddingValidations: () => state.embedHost.getEmbeddingValidations(),
+    getEmbeddingSaveCount: () => state.embedHost.getEmbeddingSaveCount()
   };
   replicaStates.set(controller, state);
   return controller;
@@ -5997,8 +6316,25 @@ function createFakeBridgeHost(options = {}) {
       (port) => port.postMessage({ protocol: PROTOCOL, kind: "embed-event", event: { type: "agentTools", ...event } })
     );
   });
+  state.embedHost.onSaved((event) => {
+    connectedPorts.forEach(
+      (port) => port.postMessage({ protocol: PROTOCOL, kind: "embed-event", event: { type: "saved", ...event } })
+    );
+  });
   const embeddingRequests = /* @__PURE__ */ new Map();
   let embeddingRequestCounter = 0;
+  function pushEmbeddingRequest(request, params) {
+    embeddingRequestCounter += 1;
+    const requestId = `embedding-request-${embeddingRequestCounter}`;
+    return new Promise((resolve, reject) => {
+      embeddingRequests.set(requestId, { resolve, reject });
+      connectedPorts.forEach(
+        (port) => port.postMessage({ protocol: PROTOCOL, kind: "embedding-request", requestId, request, ...params ? { params } : {} })
+      );
+    });
+  }
+  const embedRequests = /* @__PURE__ */ new Map();
+  let embedRequestCounter = 0;
   const beforeCloseWaiters = /* @__PURE__ */ new Map();
   let beforeCloseCounter = 0;
   const viewSessions = /* @__PURE__ */ new Map();
@@ -6235,8 +6571,66 @@ function createFakeBridgeHost(options = {}) {
       case "embeds.open": {
         const input = params.input;
         const embedId = await state.embedHost.openEmbed(input);
-        return input.placement === "frame" && options.embedFrameUrl ? { embedId, frame: { url: options.embedFrameUrl } } : { embedId };
+        const supports = state.embedHost.listEmbeds().find((entry) => entry.embedId === embedId)?.supports ?? [];
+        return {
+          embedId,
+          ...input.placement === "frame" && options.embedFrameUrl ? { frame: { url: options.embedFrameUrl } } : {},
+          ...supports.length ? { supports } : {}
+        };
+      }
+      case "embeds.inspect":
+        return await state.embedHost.inspectEmbed(
+          String(params.embedId),
+          params.request
+        );
+      case "embeds.setBeforeSave": {
+        const embedId = String(params.embedId);
+        state.embedHost.setBeforeSave(
+          embedId,
+          params.enabled === true ? (input) => {
+            embedRequestCounter += 1;
+            const requestId = `embed-request-${embedRequestCounter}`;
+            return new Promise((resolve) => {
+              embedRequests.set(requestId, (result) => resolve(result));
+              connectedPorts.forEach(
+                (port) => port.postMessage({
+                  protocol: PROTOCOL,
+                  kind: "embed-request",
+                  requestId,
+                  embedId,
+                  request: "beforeSave",
+                  params: { inspection: input.inspection, root: input.root }
+                })
+              );
+            });
+          } : null,
+          params.inspect
+        );
+        return { ok: true };
       }
+      case "embeds.respond": {
+        const resolve = embedRequests.get(String(params.requestId));
+        embedRequests.delete(String(params.requestId));
+        resolve?.(params.ok === true ? params.result : { issues: [] });
+        return { ok: true };
+      }
+      case "embeds.showIssues":
+        await state.embedHost.showEmbedIssues(String(params.embedId), params.issues);
+        return { ok: true };
+      case "embeds.reveal":
+        await state.embedHost.revealInEmbed(String(params.embedId), params.anchor);
+        return { ok: true };
+      case "embeds.callTool":
+        return await state.embedHost.callEmbedTool(
+          String(params.embedId),
+          String(params.name),
+          params.input ?? {}
+        );
+      case "embedding.validate":
+        return await state.embedHost.validateEmbedding({ interactive: params.interactive !== false });
+      case "embedding.saved":
+        state.embedHost.recordEmbeddingSaved();
+        return { ok: true };
       case "embeds.requestAccess":
         return await state.embedHost.embeds.requestAccess(
           params.input ?? { components: [] }
@@ -6269,9 +6663,10 @@ function createFakeBridgeHost(options = {}) {
         const pending = embeddingRequests.get(String(params.requestId));
         embeddingRequests.delete(String(params.requestId));
         if (params.ok === true) {
-          pending?.resolve();
+          pending?.resolve(params.result);
         } else {
-          pending?.reject(new Error(typeof params.error === "string" ? params.error : "Save failed."));
+          const message = typeof params.error === "string" ? params.error : "Save failed.";
+          pending?.reject(Object.assign(new Error(message), message === "unsupported" ? { name: "unsupported" } : {}));
         }
         return { ok: true };
       }
@@ -6909,16 +7304,23 @@ function createFakeBridgeHost(options = {}) {
     setEmbedAgentTools: (embedId, names, toolOptions) => state.embedHost.setEmbedAgentTools(embedId, names, toolOptions),
     failNextEmbedSave: (message) => state.embedHost.failNextSave(message),
     getEmbeddingDirty: () => state.embedHost.getEmbeddingDirty(),
-    requestEmbeddingSave() {
-      embeddingRequestCounter += 1;
-      const requestId = `embedding-request-${embeddingRequestCounter}`;
-      return new Promise((resolve, reject) => {
-        embeddingRequests.set(requestId, { resolve, reject });
-        connectedPorts.forEach(
-          (port) => port.postMessage({ protocol: PROTOCOL, kind: "embedding-request", requestId, request: "save" })
-        );
-      });
+    async requestEmbeddingSave() {
+      await pushEmbeddingRequest("save");
+    },
+    validateEmbed: (embedId, validateOptions) => state.embedHost.validateEmbed(embedId, validateOptions),
+    notifyEmbedSaved: (embedId) => state.embedHost.notifyEmbedSaved(embedId),
+    getEmbedRequests: (embedId) => state.embedHost.getEmbedRequests(embedId),
+    async requestEmbeddingInspection(request) {
+      return await pushEmbeddingRequest("inspect", { request: request ?? {} });
+    },
+    async requestEmbeddingShowIssues(issues) {
+      await pushEmbeddingRequest("showIssues", { issues });
+    },
+    async requestEmbeddingReveal(anchor) {
+      await pushEmbeddingRequest("reveal", { anchor });
     },
+    getEmbeddingValidations: () => state.embedHost.getEmbeddingValidations(),
+    getEmbeddingSaveCount: () => state.embedHost.getEmbeddingSaveCount(),
     dispose() {
       restoreWindow();
       connectedPorts.forEach((port) => {
@@ -7040,7 +7442,9 @@ export {
   DEFAULT_TEST_HOST_USERS,
   MockForbiddenError,
   TEST_HOST_LOCALES,
+  assertAgentManifest,
   capabilitiesForDefinitionPermissions,
+  checkAgentManifest,
   createBrowserTestHost,
   createEvaluatingViewNavigator,
   createFakeBridgeHost,