@digimuza/system-core 0.2.0-rc.2 → 0.3.0-rc.1

package/src/search/index.ts

@@ -0,0 +1,198 @@
+// `@digimuza/system-core/search` (DIG-72): one global search over every
+// installed module. Each module contributes a provider guarded by one of its
+// own permissions; the query only runs the providers the caller may use now.
+//
+//   // convex/search.ts
+//   import { defineSearch } from "@digimuza/system-core/search"
+//   import { financeSearch } from "@digimuza/system-core/finance"
+//   export const { search } = defineSearch(system, { providers: [financeSearch] }).functions
+import { queryGeneric } from "convex/server"
+import { v } from "convex/values"
+import { decide, isModuleEnabled, isSuperActor, requireHuman, type Actor } from "../core/access.js"
+import { MODULE_ID, PERMISSION_ID } from "../core/catalog.js"
+import type { SystemContext } from "../core/context.js"
+import { validation } from "../core/errors.js"
+import { toConvexError, type ConvexSystem } from "../convex/functions.js"
+
+export const SEARCH_QUERY_MIN = 2
+export const SEARCH_QUERY_MAX = 100
+/** Hits per provider when the caller passes no `limit`. */
+export const SEARCH_DEFAULT_LIMIT = 5
+/** Largest `limit` (hits per provider). */
+export const SEARCH_PROVIDER_MAX = 20
+/** Hits across all providers. */
+export const SEARCH_TOTAL_MAX = 50
+
+/** `module.name`, e.g. `finance.invoices`. */
+export const SEARCH_PROVIDER_ID = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_-]*$/
+
+export interface SearchHit {
+  /** Set by the search to the provider's id. */
+  providerId: string
+  /** Stable id of the hit within the provider (e.g. the document id). */
+  id: string
+  title: string
+  subtitle?: string
+  /** App-relative link, `/app/...`. Hits with any other href are dropped. */
+  href: string
+  /** Optional kind for an icon (e.g. `invoice`). */
+  kind?: string
+}
+
+/** What a provider's `search` gets. Runs inside the search query (read-only). */
+export interface SearchContext {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any
+  sys: SystemContext
+  actor: Actor
+}
+
+export interface SearchProvider {
+  /** Stable `module.name`, starts with `${moduleId}.`. */
+  id: string
+  /** Owning module: the provider is skipped while it is disabled (except for an effective Super). */
+  moduleId: string
+  /** Fallback group label; the app translates by `id`. */
+  label: string
+  /** The owning module's permission the caller must hold now (checked with `decide`). */
+  permission: string
+  /** Trimmed, validated query; return at most `limit` hits, best first. */
+  search(ctx: SearchContext, input: { query: string; limit: number }): Promise<Omit<SearchHit, "providerId">[] | SearchHit[]>
+}
+
+export interface SearchGroup {
+  providerId: string
+  moduleId: string
+  label: string
+  hits: SearchHit[]
+}
+
+export interface SearchResult {
+  /** The trimmed query. */
+  query: string
+  /** Providers with at least one hit, in the order they were installed. */
+  groups: SearchGroup[]
+  /** Hits across all groups (≤ SEARCH_TOTAL_MAX). */
+  total: number
+}
+
+/** Declares a provider. Identity at runtime; validates ids and the permission format. */
+export function defineSearchProvider<const P extends SearchProvider>(provider: P): P {
+  const id = typeof provider?.id === "string" ? provider.id : ""
+  if (!SEARCH_PROVIDER_ID.test(id)) throw new Error(`defineSearchProvider: invalid id "${id}" (expected module.name, e.g. finance.invoices)`)
+  if (typeof provider.moduleId !== "string" || !MODULE_ID.test(provider.moduleId)) throw new Error(`defineSearchProvider(${id}): invalid moduleId`)
+  if (!id.startsWith(`${provider.moduleId}.`)) throw new Error(`defineSearchProvider(${id}): id must start with "${provider.moduleId}."`)
+  if (typeof provider.permission !== "string" || !PERMISSION_ID.test(provider.permission)) throw new Error(`defineSearchProvider(${id}): invalid permission`)
+  if (typeof provider.label !== "string" || !provider.label.trim()) throw new Error(`defineSearchProvider(${id}): label is required`)
+  if (typeof provider.search !== "function") throw new Error(`defineSearchProvider(${id}): search must be a function`)
+  return provider
+}
+
+const SAFE_HREF = /^\/(?!\/)[^\s\\]*$/
+const clip = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
+
+/** Keeps well-formed hits with a safe, app-relative href. */
+function cleanHit(providerId: string, raw: unknown): SearchHit | null {
+  if (!raw || typeof raw !== "object") return null
+  const h = raw as Record<string, unknown>
+  if (typeof h.id !== "string" || !h.id || typeof h.title !== "string" || !h.title.trim()) return null
+  if (typeof h.href !== "string" || h.href.length > 500 || !SAFE_HREF.test(h.href)) return null
+  const hit: SearchHit = { providerId, id: h.id, title: clip(h.title.trim(), 200), href: h.href }
+  if (typeof h.subtitle === "string" && h.subtitle.trim()) hit.subtitle = clip(h.subtitle.trim(), 300)
+  if (typeof h.kind === "string" && h.kind) hit.kind = clip(h.kind, 40)
+  return hit
+}
+
+/** Trims and checks the query; throws VALIDATION (`fields: ["query"]`). */
+export function normalizeSearchQuery(query: string): string {
+  const q = query.replace(/\s+/g, " ").trim()
+  if (q.length < SEARCH_QUERY_MIN) throw validation("query_too_short", ["query"])
+  if (q.length > SEARCH_QUERY_MAX) throw validation("query_too_long", ["query"])
+  return q
+}
+
+/** Runs the providers the actor may use. No audit: it is a read. */
+export async function runSearch(
+  ctx: { db: unknown },
+  sys: SystemContext,
+  actor: Actor,
+  providers: readonly SearchProvider[],
+  input: { query: string; limit?: number | undefined },
+): Promise<SearchResult> {
+  const query = normalizeSearchQuery(input.query)
+  const perProvider = Math.min(Math.max(1, Math.floor(input.limit ?? SEARCH_DEFAULT_LIMIT)), SEARCH_PROVIDER_MAX)
+  const isSuper = await isSuperActor(sys, actor)
+  const groups: SearchGroup[] = []
+  let total = 0
+  for (const provider of providers) {
+    if (total >= SEARCH_TOTAL_MAX) break
+    if (!isSuper && !isModuleEnabled(sys, await sys.store.get("modules", provider.moduleId))) continue
+    if (!(await decide(sys, actor, provider.permission)).allowed) continue
+    const limit = Math.min(perProvider, SEARCH_TOTAL_MAX - total)
+    let raw: unknown[]
+    try {
+      raw = (await provider.search({ db: ctx.db, sys, actor }, { query, limit })) ?? []
+    } catch (error) {
+      // One failing provider never fails the whole search. The query is not logged.
+      sys.logger.error("search_provider_failed", { providerId: provider.id, error })
+      continue
+    }
+    const hits: SearchHit[] = []
+    const seen = new Set<string>()
+    for (const r of Array.isArray(raw) ? raw : []) {
+      const hit = cleanHit(provider.id, r)
+      if (!hit || seen.has(hit.id)) continue
+      seen.add(hit.id)
+      hits.push(hit)
+      if (hits.length >= limit) break
+    }
+    if (!hits.length) continue
+    groups.push({ providerId: provider.id, moduleId: provider.moduleId, label: provider.label, hits })
+    total += hits.length
+  }
+  return { query, groups, total }
+}
+
+export interface SearchOptions {
+  providers: readonly SearchProvider[]
+}
+
+/**
+ * The search's Convex functions, bound to the app's system:
+ *   export const { search } = defineSearch(system, { providers: [financeSearch] }).functions
+ */
+export function defineSearch(system: ConvexSystem, options: SearchOptions) {
+  const catalog = system.definition.catalog
+  const ids = new Set<string>()
+  for (const p of options.providers) {
+    if (ids.has(p.id)) throw new Error(`defineSearch: duplicate provider id "${p.id}"`)
+    ids.add(p.id)
+    if (!catalog.modules.has(p.moduleId)) throw new Error(`defineSearch(${p.id}): module "${p.moduleId}" is not installed in this system`)
+    if (!catalog.permissions.has(p.permission)) throw new Error(`defineSearch(${p.id}): unknown permission "${p.permission}"`)
+  }
+  const providers = [...options.providers]
+
+  return {
+    functions: {
+      /**
+       * `({ query, limit? })` → SearchResult. Human sessions only (API keys: FORBIDDEN).
+       * `limit` is hits per provider (default 5, max 20); at most 50 in total.
+       * VALIDATION (`fields: ["query"]`) unless 2–100 characters after trimming.
+       */
+      search: queryGeneric({
+        args: { query: v.string(), limit: v.optional(v.number()), apiKey: v.optional(v.string()), operationId: v.optional(v.string()) },
+        handler: async (ctx, a): Promise<SearchResult> => {
+          const { sys, actor } = await system.context(ctx, { apiKey: a.apiKey, operationId: a.operationId })
+          try {
+            const human = requireHuman(sys, actor)
+            return await runSearch(ctx, sys, human, providers, { query: a.query, limit: a.limit })
+          } catch (e) {
+            throw toConvexError(e, sys.operationId)
+          }
+        },
+      }),
+    },
+  }
+}
+
+export type SearchFunctions = ReturnType<typeof defineSearch>["functions"]