@k2b/cloud 0.37.0 → 0.39.0

package/src/browser/choose-files.browser-harness.tsx

@@ -3,7 +3,8 @@ import { chooseFiles } from "./files";
 
 /**
  * One "Attach" button that calls the real `chooseFiles` for a browser test, which answers the catalog, the
- * provider's Queries, and its read streams. `?single` chooses one file, `?accept=` and `?max=` pass through.
+ * provider's Queries, and its read streams. `?single` chooses one file, `?accept=` and `?max=` pass through,
+ * `?customer=` passes one `customers.customer` ref as context and `?noMatching=` its empty title.
  * Each call gets a fresh signal that `window.abortChoosing()` aborts. Each result lands in `window.chosen` as plain
  * facts. `?dropzone` opens, like Notebooks, a dialog whose `FileDropzone` chooses with
  * `chooseFiles`; what it hands over lands in `window.chosen` the same way.
@@ -43,6 +44,8 @@ button.addEventListener("click", () => {
     multiple: !params.has("single"),
     accept: params.get("accept") ?? undefined,
     maxBytes: params.has("max") ? Number(params.get("max")) : undefined,
+    context: params.has("customer") ? { refs: [{ type: "customers.customer", id: params.get("customer")! }] } : undefined,
+    noMatchingFiles: params.get("noMatching") ?? undefined,
     signal: choosing.signal,
   }).then(async (files) => void results.push(await facts(files)));
 });

package/src/browser/composer-catalog.ts

@@ -0,0 +1,103 @@
+import type { ChatCommandSearch } from "@k2b/ui";
+import { createSignal } from "solid-js";
+import { listCapabilityCatalog } from "../capabilities/client";
+import { LOCALE_HEADER } from "../shared/locale";
+
+export type CloudSearchTag = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  tag: string;
+  title: string;
+  description: string;
+  aliases: readonly string[];
+};
+
+/**
+ * What composers read from the page's one Capability catalog load. It leaves out the tags of apps without a resource
+ * reader: a picker that requires one can show none of their results. A composer that reads such a type itself adds its
+ * tag on its own and names the type in `cloudInsertMenu`'s `ownReaders`.
+ */
+export type CloudComposerCatalog = { tags: readonly CloudSearchTag[] };
+
+/** The budget of one Capability query (and of resolving a Command), applied to each catalog page. */
+const CATALOG_PAGE_TIMEOUT_MS = 15_000;
+
+const catalogs = new Map<string, Promise<CloudComposerCatalog>>();
+
+const loadCatalog = async (locale: string): Promise<CloudComposerCatalog> => {
+  const tags: CloudSearchTag[] = [];
+  const seen = new Set<string>();
+  let cursor: string | undefined;
+  do {
+    // A page that never answers fails like any other, so the load is forgotten and the next opening asks again.
+    const result = await listCapabilityCatalog({
+      limit: 25,
+      cursor,
+      headers: { [LOCALE_HEADER]: locale },
+      signal: AbortSignal.timeout(CATALOG_PAGE_TIMEOUT_MS),
+    });
+    if (!result.ok) throw new Error(result.error.message);
+    for (const app of result.data.apps) {
+      if (!app.manifest.types.some((type) => type.reader)) continue;
+      for (const query of app.manifest.queries) {
+        for (const tag of query.universalSearch?.tags ?? []) {
+          const key = `${app.appId}\u0000${tag.tag}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          tags.push({ appId: app.appId, appName: app.appName, appIcon: app.appIcon, ...tag, aliases: tag.aliases ?? [] });
+        }
+      }
+    }
+    const next = result.data.page.hasMore ? result.data.page.nextCursor : undefined;
+    if (next && cursor && next <= cursor) throw new Error("Invalid Composer catalog cursor");
+    cursor = next;
+  } while (cursor);
+  return { tags };
+};
+
+/**
+ * One catalog load per page and locale, shared by every composer on the page. A failed load is forgotten,
+ * so the next menu opening can try again; nothing polls or retries on its own.
+ */
+export const loadCloudComposerCatalog = (locale: string): Promise<CloudComposerCatalog> => {
+  const cached = catalogs.get(locale);
+  if (cached) return cached;
+  const pending = loadCatalog(locale).catch((error: unknown) => {
+    if (catalogs.get(locale) === pending) catalogs.delete(locale);
+    throw error;
+  });
+  catalogs.set(locale, pending);
+  return pending;
+};
+
+/**
+ * The search tags of one composer. Call `ready` at the start of every `searchCommands` run: each menu opening starts
+ * the shared load once, so only the first opening, or one after a failure, sends a request, and no keystroke does.
+ * A search with typed text and no scope waits for that answer, so "/notiz" never settles as "nothing found" before its
+ * tag arrives. The overview and scoped searches do not wait, and after a failed load no search waits again; a later
+ * success still brings the tags in. A failure keeps the tags the composer had.
+ */
+export function createCloudComposerCatalog(load: (locale: string) => Promise<CloudComposerCatalog> = loadCloudComposerCatalog) {
+  const [tags, setTags] = createSignal<readonly CloudSearchTag[]>([]);
+  let opening: number | undefined;
+  let settled: Promise<void> = Promise.resolve();
+  let failed = false;
+  return {
+    tags,
+    ready(query: string, search: ChatCommandSearch, locale: string): Promise<void> {
+      if (opening !== search.opening) {
+        opening = search.opening;
+        settled = load(locale).then(
+          (catalog) => {
+            setTags(catalog.tags);
+          },
+          () => {
+            failed = true;
+          },
+        );
+      }
+      return failed || search.scope !== undefined || !query.trim() ? Promise.resolve() : settled;
+    },
+  };
+}

package/src/browser/composer-insert-messages.ts

@@ -0,0 +1,31 @@
+import { i18n } from "@k2b/stdlib";
+
+export const composerInsertMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      insertFromCloud: "Insert from Cloud",
+      insertFromCloudHint: "Find something in your apps and insert it",
+      insertTag: ({ tag }: { tag: string }) => `Insert ${tag}`,
+      chooseFrom: ({ app }: { app: string }) => `Choose from ${app}`,
+      tagFromApp: ({ tag, app }: { tag: string; app: string }) => `${tag} from ${app}`,
+      searchTagFor: ({ tag, query }: { tag: string; query: string }) => `Search ${tag} for “${query}”`,
+      searchTag: ({ tag }: { tag: string }) => `Search ${tag}`,
+      fromAppWithPreview: ({ app }: { app: string }) => `From ${app}, with preview`,
+      searchCloudFor: ({ query }: { query: string }) => `Search Cloud for “${query}”`,
+      searchAllApps: "Search all apps for content",
+    },
+    de: {
+      insertFromCloud: "Aus Cloud einfügen",
+      insertFromCloudHint: "Etwas aus deinen Apps suchen und einfügen",
+      insertTag: ({ tag }) => `${tag} einfügen`,
+      chooseFrom: ({ app }) => `Aus ${app} wählen`,
+      tagFromApp: ({ tag, app }) => `${tag} aus ${app}`,
+      searchTagFor: ({ tag, query }) => `„${query}“ in ${tag} suchen`,
+      searchTag: ({ tag }) => `${tag} durchsuchen`,
+      fromAppWithPreview: ({ app }) => `Aus ${app}, mit Vorschau`,
+      searchCloudFor: ({ query }) => `„${query}“ in Cloud suchen`,
+      searchAllApps: "In allen Apps nach Inhalten suchen",
+    },
+  },
+});

package/src/browser/composer-insert.ts

@@ -0,0 +1,150 @@
+import type { ChatAttachment, ChatCommand, ChatCommandResult, ChatCommandScope } from "@k2b/ui";
+import type { CloudResourceRef } from "../contracts";
+import type { CloudSearchTag } from "./composer-catalog";
+import { composerInsertMessages } from "./composer-insert-messages";
+import { type CloudResourcePickerItem, openCloudResourcePicker } from "./resource-picker";
+
+export {
+  type CloudComposerCatalog,
+  type CloudSearchTag,
+  createCloudComposerCatalog,
+  loadCloudComposerCatalog,
+} from "./composer-catalog";
+
+export type CloudInsertMenuOptions = {
+  locale: string;
+  /** Every app's search tags, from `loadCloudComposerCatalog`. */
+  tags: readonly CloudSearchTag[];
+  /** Section of the rows in the composer's slash list. */
+  section?: string;
+  /** Turns the chosen resource into the reference the composer puts where `/…` was. */
+  mention: (item: CloudResourcePickerItem) => ChatAttachment;
+  /** References the draft already holds; the picker leaves them out. Read when the picker opens. */
+  excludeRefs?: () => readonly CloudResourceRef[];
+  /** Why nothing can be inserted now, such as a full message; it replaces each row's description. */
+  reason?: string;
+  /** First words of the composer's own scopes. A tag never claims them, so they keep narrowing as before. */
+  reservedWords?: readonly string[];
+  /** More first words for one tag, keyed `appId:tag`, such as a short word an app uses for its own tag. */
+  scopeWords?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Tags, keyed `appId:tag`, whose resources of one type this composer reads itself, such as
+   * `{ "assistant:studio-app": "assistant.app" }`. Their picker lists only that type, also without a Cloud reader, even
+   * after the person removes the scope chip. Every other picker lists only resources with a reader (`requireReader`).
+   */
+  ownReaders?: Readonly<Record<string, string>>;
+};
+
+export type CloudInsertMenu = {
+  /** "Insert from Cloud": the picker across all apps. */
+  insert: ChatCommand;
+  /** One row per search tag, only while searching. Enter opens the picker narrowed to the tag; Tab narrows the list. */
+  tags: ChatCommand[];
+  /** One scope per tag that keeps a first word of its own, titled like "Notes from Notebooks". */
+  scopes: ChatCommandScope[];
+  /** For the composer's `commandFallback`: "Search Notes for “q3”" in a tag scope, "Search Cloud for “q3”" otherwise. */
+  fallback: (search: { query: string; scope?: string }) => ChatCommand | undefined;
+};
+
+const fold = (text: string) => text.toLowerCase().normalize("NFD").replace(/\p{M}/gu, "").replace(/ß/g, "ss");
+const tagKey = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `${tag.appId}:${tag.tag}`;
+const scopeId = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `cloud-tag:${tagKey(tag)}`;
+
+/**
+ * Slash-list rows that insert Cloud content the person can read. Every row opens the resource picker, narrowed on the
+ * server to an app and tag when it has one, and hands the chosen item back as a `mention` for the token's place.
+ */
+export const cloudInsertMenu = (options: CloudInsertMenuOptions): CloudInsertMenu => {
+  const t = composerInsertMessages.resolve([options.locale]).t;
+  const pick = async (tag: CloudSearchTag | undefined, query: string): Promise<ChatCommandResult> => {
+    const ownType = tag ? options.ownReaders?.[tagKey(tag)] : undefined;
+    const item = await openCloudResourcePicker({
+      title: tag ? t.insertTag({ tag: tag.title }) : t.insertFromCloud,
+      scope: tag ? { appId: tag.appId, tag: tag.tag, label: `${tag.title} · ${tag.appName}`, icon: tag.appIcon } : undefined,
+      query: query || undefined,
+      ...(ownType ? { resourceType: ownType } : { requireReader: true }),
+      excludeRefs: options.excludeRefs?.(),
+    });
+    return item ? { mention: options.mention(item) } : "cancelled";
+  };
+
+  const reserved = new Set((options.reservedWords ?? []).map(fold));
+  // The title comes first, so Tab writes the word the person reads ("notizen ").
+  const candidates = options.tags.map((tag) => {
+    const title = fold(tag.title);
+    return [
+      ...new Set(
+        [...(/\s/.test(title) ? [] : [title]), tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])]
+          .map(fold)
+          .filter((word) => word && !/\s/.test(word) && !reserved.has(word)),
+      ),
+    ];
+  });
+  // A word two tags share narrows to neither, so Tab on either row would leave the list unscoped; neither keeps it.
+  const uses = new Map<string, number>();
+  for (const word of candidates.flat()) uses.set(word, (uses.get(word) ?? 0) + 1);
+  const scoped = new Map<string, CloudSearchTag>();
+  const scopes: ChatCommandScope[] = [];
+  const tags = options.tags.map((tag, index): ChatCommand => {
+    const words = candidates[index]!.filter((word) => uses.get(word) === 1);
+    if (words.length) {
+      scoped.set(scopeId(tag), tag);
+      scopes.push({ id: scopeId(tag), title: t.tagFromApp({ tag: tag.title, app: tag.appName }), words });
+    }
+    return {
+      id: scopeId(tag),
+      section: options.section,
+      name: tag.tag,
+      label: tag.title,
+      description: t.chooseFrom({ app: tag.appName }),
+      icon: tag.appIcon,
+      keywords: [tag.title, tag.appName, tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])],
+      app: tag.appName,
+      scope: words.length ? scopeId(tag) : undefined,
+      hiddenUntilSearch: true,
+      reason: options.reason,
+      action: () => pick(tag, ""),
+    };
+  });
+
+  return {
+    insert: {
+      id: "cloud-insert",
+      section: options.section,
+      name: "cloud",
+      label: t.insertFromCloud,
+      description: t.insertFromCloudHint,
+      icon: "ti ti-cloud-search",
+      keywords: ["cloud", "insert", "einfügen", "inhalt", "content", "ressource", "resource", "verweis", "reference", "link"],
+      reason: options.reason,
+      action: () => pick(undefined, ""),
+    },
+    tags,
+    scopes,
+    fallback: ({ query, scope }) => {
+      if (scope !== undefined) {
+        const tag = scoped.get(scope);
+        if (!tag) return undefined;
+        return {
+          id: `cloud-search:${tagKey(tag)}`,
+          name: `cloud-search:${tagKey(tag)}`,
+          label: query ? t.searchTagFor({ tag: tag.title, query }) : t.searchTag({ tag: tag.title }),
+          description: t.fromAppWithPreview({ app: tag.appName }),
+          icon: "ti ti-search",
+          reason: options.reason,
+          action: () => pick(tag, query),
+        };
+      }
+      if (!query) return undefined;
+      return {
+        id: "cloud-search",
+        name: "cloud-search",
+        label: t.searchCloudFor({ query }),
+        description: t.searchAllApps,
+        icon: "ti ti-search",
+        reason: options.reason,
+        action: () => pick(undefined, query),
+      };
+    },
+  };
+};

package/src/browser/file-chooser-messages.ts

@@ -19,6 +19,8 @@ export const fileChooserMessages = i18n.define({
       loading: "Loading…",
       loadMore: "Load more",
       emptyFolder: "This folder is empty",
+      noMatchingFiles: "No matching files",
+      otherSource: "Choose another source",
       noMatches: ({ query }: { query: string }) => `Nothing matches “${query}”`,
       clearFilter: "Clear filter",
       offline: "You are offline",
@@ -92,6 +94,8 @@ export const fileChooserMessages = i18n.define({
       loading: "Wird geladen…",
       loadMore: "Mehr laden",
       emptyFolder: "Dieser Ordner ist leer",
+      noMatchingFiles: "Keine passenden Dateien",
+      otherSource: "Andere Quelle wählen",
       noMatches: ({ query }) => `Nichts passt zu „${query}“`,
       clearFilter: "Filter löschen",
       offline: "Du bist offline",

package/src/browser/file-providers.ts

@@ -6,12 +6,14 @@ import type { CapabilityCatalogApp, CapabilityClientError, CapabilityHttpOptions
 import { CapabilityErrorSchema, type CapabilityStream, capabilityResultSchema } from "../contracts/capabilities";
 import { CapabilityStreamStatusSchema } from "../contracts/capability-streams";
 import {
+  type FileProviderContext,
   type FileProviderEntry,
   type FileProviderIssue,
   FileProviderListDataSchema,
   FileProviderReadDataSchema,
   FileProviderSaveDataSchema,
   FileProviderSaveInputSchema,
+  fileProviderAcceptsContext,
   fileProviderIssues,
 } from "../contracts/file-provider";
 import { LOCALE_HEADER } from "../shared/locale";
@@ -25,6 +27,7 @@ export type FileProviderSource = {
   name: string;
   icon: string;
   list: string;
+  context: boolean;
   read: string;
   /** The provider's read limit; a consumer combines it with its own. */
   maxBytes: number;
@@ -61,6 +64,14 @@ const issuesOf = (app: CapabilityCatalogApp): FileProviderIssue[] | null => {
   }
 };
 
+const acceptsContext = (app: CapabilityCatalogApp): boolean => {
+  try {
+    return fileProviderAcceptsContext(app.manifest);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Keeps the catalog apps that offer files with a usable `list` and `read`. Core already drops invalid declarations;
  * the check repeats here because a manifest from another Cloud release may name an operation this reader left out.
@@ -81,6 +92,7 @@ export const fileProviderSources = (apps: readonly CapabilityCatalogApp[], local
           name: app.appName,
           icon: providerIcon(app.appIcon, "ti ti-folders"),
           list: declaration.list,
+          context: acceptsContext(app),
           read: declaration.read,
           maxBytes: read.stream.maxBytes,
           ...(save?.stream ? { save: { id: save.localId, maxBytes: save.stream.maxBytes } } : {}),
@@ -112,7 +124,7 @@ export type FileProviderPage = { items: FileProviderEntry[]; next: string | null
 /** One folder page. Without `parent` it is the provider's root. */
 export const listProviderFolder = async (
   provider: FileProviderSource,
-  input: { parent?: string; query?: string; cursor?: string },
+  input: { parent?: string; query?: string; cursor?: string; context?: FileProviderContext },
   caller: FileProviderCaller,
   signal?: AbortSignal,
 ): Promise<FileProviderPage> => {
@@ -125,6 +137,7 @@ export const listProviderFolder = async (
         ...(input.parent === undefined ? {} : { parent: input.parent }),
         ...(input.query ? { query: input.query } : {}),
         ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+        ...(provider.context === true && input.context !== undefined ? { context: input.context } : {}),
         limit: FILE_PROVIDER_PAGE_SIZE,
       },
       signal,

package/src/browser/panel-messages.ts

@@ -0,0 +1,24 @@
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export function isPanelReadyMessage(value: unknown, provider: string): value is { type: "cloud.panel.ready"; v: 1; provider: string } {
+  return (
+    isRecord(value) &&
+    Reflect.ownKeys(value).length === 3 &&
+    Object.hasOwn(value, "type") &&
+    Object.hasOwn(value, "v") &&
+    Object.hasOwn(value, "provider") &&
+    value.type === "cloud.panel.ready" &&
+    value.v === 1 &&
+    typeof value.provider === "string" &&
+    value.provider === provider
+  );
+}
+
+export function isPanelCloseMessage(value: unknown): value is { type: "cloud.panel.close"; v?: 1 } {
+  return (
+    isRecord(value) &&
+    Object.hasOwn(value, "type") &&
+    value.type === "cloud.panel.close" &&
+    (Reflect.ownKeys(value).length === 1 || (Reflect.ownKeys(value).length === 2 && Object.hasOwn(value, "v") && value.v === 1))
+  );
+}