@fayz-ai/core 0.1.6

package/src/plugin/runtime.ts

@@ -0,0 +1,313 @@
+import * as React from 'react'
+import type {
+  PluginManifest,
+  PluginRuntime,
+  PluginRuntimeContext,
+  PluginRuntimeIssue,
+  PluginRuntimeRoute,
+  PluginSettingsTab,
+  PluginWidgetDefinition,
+  PluginWidgetZone,
+  ResolvedPluginManifest,
+  ResolvedPluginWidget,
+  TenantPluginBinding,
+  PluginRegistryDef,
+  PluginAITool,
+  PluginNavigationEntry,
+  PluginCapability,
+  PluginWidgetVisibility,
+  ResolvedDashboardWidget,
+  DashboardSurface,
+} from '../types/plugins'
+import type { FeatureDeclaration } from '../types/permissions'
+import { getComponent } from '../registry'
+
+/** The plugin contract version this runtime understands. A plugin declaring a
+ *  higher apiVersion is rejected rather than mis-rendered. */
+export const PLUGIN_API_VERSION = 1
+
+/** Resolve a plugin route/widget/settings/onboarding target to a component,
+ *  whether it provided the component directly or a registered component id. */
+export function resolvePluginComponent(
+  def: { component?: React.ComponentType<unknown>; componentId?: string },
+): React.ComponentType<unknown> | undefined {
+  if (def.component) return def.component
+  if (def.componentId) return getComponent(def.componentId) as React.ComponentType<unknown> | undefined
+  return undefined
+}
+
+interface ResolvePluginRuntimeOptions {
+  plugins?: PluginManifest[]
+  tenantPlugins?: TenantPluginBinding[]
+  hasTenantBindings?: boolean
+  context: PluginRuntimeContext
+}
+
+const EMPTY_CONTEXT: PluginRuntimeContext = {
+  tenant: null,
+  user: null,
+  currentPath: '/',
+  matchedPath: '/',
+  layout: 'sidebar',
+}
+
+function slugify(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+}
+
+function matchesRoutePattern(pattern: string, currentPath: string): boolean {
+  if (pattern === currentPath) return true
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2)
+    return currentPath === base || currentPath.startsWith(`${base}/`)
+  }
+  if (pattern.endsWith('*')) return currentPath.startsWith(pattern.slice(0, -1))
+  return false
+}
+
+function isWidgetVisible(widget: ResolvedPluginWidget, context: PluginRuntimeContext): boolean {
+  if (widget.permission && context.hasPermission && !context.hasPermission(widget.permission)) return false
+  const visibility: PluginWidgetVisibility | undefined = widget.visibility
+  if (!visibility) return true
+
+  if (visibility.layouts && !visibility.layouts.includes(context.layout)) return false
+  if (visibility.roles && context.user?.role && !visibility.roles.includes(context.user.role)) return false
+  if (visibility.roles && !context.user?.role) return false
+  if (visibility.plans && context.tenant?.plan && !visibility.plans.includes(context.tenant.plan)) return false
+  if (visibility.plans && !context.tenant?.plan) return false
+  if (visibility.routes && !visibility.routes.some((p) => matchesRoutePattern(p, context.currentPath))) return false
+  if (visibility.excludeRoutes?.some((p) => matchesRoutePattern(p, context.currentPath))) return false
+  if (visibility.permissions?.length) {
+    if (!context.hasPermission) return false
+    if (!visibility.permissions.every((req) => context.hasPermission?.(req))) return false
+  }
+  if (visibility.when && !visibility.when(context)) return false
+  return true
+}
+
+function normalizeSettingsTabs(plugin: PluginManifest): PluginSettingsTab[] {
+  return (plugin.settings ?? []).map((entry, index) => ({
+    ...entry,
+    pluginId: entry.pluginId ?? plugin.id,
+    order: entry.order ?? index,
+    id: entry.id ?? `${plugin.id}-${slugify(entry.label)}`,
+  }))
+}
+
+function createEmptyRuntime(context: PluginRuntimeContext = EMPTY_CONTEXT): PluginRuntime {
+  return {
+    context,
+    plugins: [],
+    activePlugins: [],
+    routes: [],
+    navigation: [],
+    settingsTabs: [],
+    widgets: [],
+    dashboardWidgets: [],
+    capabilities: [],
+    aiTools: [],
+    registries: new Map(),
+    pluginFeatures: [],
+    issues: [],
+  }
+}
+
+export function definePlugin<T extends PluginManifest>(plugin: T): T {
+  return plugin
+}
+
+export function resolvePluginRuntime({
+  plugins = [],
+  tenantPlugins = [],
+  hasTenantBindings,
+  context,
+}: ResolvePluginRuntimeOptions): PluginRuntime {
+  if (plugins.length === 0) return createEmptyRuntime(context)
+
+  const issues: PluginRuntimeIssue[] = []
+  const normalizedPlugins = new Map<string, PluginManifest>()
+
+  for (const plugin of plugins) {
+    if (normalizedPlugins.has(plugin.id)) {
+      issues.push({ type: 'duplicate_plugin', pluginId: plugin.id, message: `Plugin "${plugin.id}" registered more than once.` })
+      continue
+    }
+    if (plugin.apiVersion != null && plugin.apiVersion > PLUGIN_API_VERSION) {
+      issues.push({
+        type: 'incompatible_api_version',
+        pluginId: plugin.id,
+        message: `Plugin "${plugin.id}" requires plugin API v${plugin.apiVersion}, but this runtime supports v${PLUGIN_API_VERSION}. Upgrade @fayz-ai/app-runtime.`,
+      })
+      continue
+    }
+    normalizedPlugins.set(plugin.id, plugin)
+  }
+
+  const bindings = new Map<string, TenantPluginBinding>()
+  for (const b of tenantPlugins) bindings.set(b.pluginId, b)
+  const bindingsAreManaged = hasTenantBindings ?? tenantPlugins.length > 0
+
+  const requested = new Set<string>()
+  const activationReason = new Map<string, ResolvedPluginManifest['activationReason']>()
+
+  for (const plugin of normalizedPlugins.values()) {
+    const binding = bindings.get(plugin.id)
+    if (binding?.status === 'active') {
+      requested.add(plugin.id)
+      activationReason.set(plugin.id, 'tenant')
+      continue
+    }
+    if (plugin.defaultEnabled === true || (!bindingsAreManaged && plugin.defaultEnabled !== false)) {
+      requested.add(plugin.id)
+      activationReason.set(plugin.id, 'default')
+    }
+  }
+
+  const orderedIds: string[] = []
+  const visiting = new Set<string>()
+  const visited = new Set<string>()
+
+  function visit(pluginId: string, ancestry: string[] = []): void {
+    if (visited.has(pluginId)) return
+    const plugin = normalizedPlugins.get(pluginId)
+    if (!plugin) return
+    if (visiting.has(pluginId)) {
+      issues.push({ type: 'circular_dependency', pluginId, message: `Circular dependency: ${[...ancestry, pluginId].join(' -> ')}.` })
+      return
+    }
+    visiting.add(pluginId)
+    for (const depId of plugin.dependencies ?? []) {
+      if (!normalizedPlugins.has(depId)) {
+        issues.push({ type: 'missing_dependency', pluginId, dependencyId: depId, message: `Plugin "${plugin.id}" depends on missing plugin "${depId}".` })
+        continue
+      }
+      if (requested.has(pluginId) && !requested.has(depId)) {
+        requested.add(depId)
+        activationReason.set(depId, 'dependency')
+      }
+      visit(depId, [...ancestry, pluginId])
+    }
+    visiting.delete(pluginId)
+    visited.add(pluginId)
+    orderedIds.push(pluginId)
+  }
+
+  for (const id of normalizedPlugins.keys()) visit(id)
+
+  const resolvedById = new Map<string, ResolvedPluginManifest>()
+
+  for (const pluginId of orderedIds) {
+    const plugin = normalizedPlugins.get(pluginId)
+    if (!plugin) continue
+    const binding = bindings.get(plugin.id)
+    const missing = (plugin.dependencies ?? []).filter((id) => !normalizedPlugins.has(id))
+    const compatible = !plugin.verticalId || plugin.verticalId === context.tenant?.verticalId
+    if (!compatible) {
+      issues.push({ type: 'vertical_mismatch', pluginId: plugin.id, message: `Plugin "${plugin.id}" requires vertical "${plugin.verticalId}".` })
+    }
+    const reason = activationReason.get(plugin.id) ?? 'inactive'
+    const depsReady = (plugin.dependencies ?? []).every((id) => resolvedById.get(id)?.isActive)
+    const explicitlyDisabled = binding?.status === 'disabled' || binding?.status === 'removed'
+    const shouldActivate = reason === 'dependency' ? true : requested.has(plugin.id) && !explicitlyDisabled
+    const isActive = shouldActivate && compatible && missing.length === 0 && depsReady
+
+    resolvedById.set(plugin.id, {
+      ...plugin,
+      status: isActive ? 'active' : (binding?.status ?? 'disabled'),
+      isActive,
+      activationReason: isActive ? reason : 'inactive',
+      config: binding?.config ?? {},
+      missingDependencies: missing,
+      settingsTabs: normalizeSettingsTabs(plugin),
+      widgets: plugin.widgets ?? [],
+      resolvedRegistries: plugin.registries ?? [],
+      resolvedAITools: plugin.aiTools ?? [],
+    })
+  }
+
+  const resolvedPlugins = orderedIds
+    .map((id) => resolvedById.get(id))
+    .filter((p): p is ResolvedPluginManifest => Boolean(p))
+
+  const activePlugins = resolvedPlugins.filter((p) => p.isActive)
+  const routes: PluginRuntimeRoute[] = []
+  const navigation: PluginNavigationEntry[] = []
+  const settingsTabs: PluginSettingsTab[] = []
+  const widgets: ResolvedPluginWidget[] = []
+  const dashboardWidgets: ResolvedDashboardWidget[] = []
+  const capabilities: PluginCapability[] = []
+  const aiTools: PluginAITool[] = []
+  const registries = new Map<string, PluginRegistryDef[]>()
+  const pluginFeatures: FeatureDeclaration[] = []
+
+  for (const plugin of activePlugins) {
+    routes.push(...plugin.routes.map((r) => ({ ...r, plugin })))
+    navigation.push(...plugin.navigation.map((entry, i) => ({
+      ...entry,
+      id: entry.id ?? `${plugin.id}:${entry.route}:${i}`,
+      icon: entry.icon ?? plugin.icon,
+    })))
+    settingsTabs.push(...plugin.settingsTabs)
+    capabilities.push(...(plugin.capabilities ?? []))
+    aiTools.push(...plugin.resolvedAITools)
+    if (plugin.resolvedRegistries.length > 0) registries.set(plugin.id, plugin.resolvedRegistries)
+    if (plugin.declaredFeatures) pluginFeatures.push(...plugin.declaredFeatures)
+    widgets.push(...plugin.widgets.map((w, i) => ({
+      ...w,
+      order: w.order ?? i,
+      config: { ...plugin.config, ...(w.props ?? {}) },
+      plugin,
+    })))
+    dashboardWidgets.push(...(plugin.dashboardWidgets ?? []).map((w, i) => ({
+      ...w,
+      domain: w.domain ?? plugin.id,
+      order: w.defaultOrder ?? i,
+      plugin,
+    })))
+  }
+
+  navigation.sort((a, b) => {
+    const order = { main: 0, secondary: 1, settings: 2 }
+    return (order[a.section] ?? 99) - (order[b.section] ?? 99) || a.position - b.position
+  })
+  settingsTabs.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  widgets.sort((a, b) => a.zone !== b.zone ? a.zone.localeCompare(b.zone) : a.order - b.order)
+  dashboardWidgets.sort((a, b) => a.order - b.order)
+
+  return { context, plugins: resolvedPlugins, activePlugins, routes, navigation, settingsTabs, widgets, dashboardWidgets, capabilities, aiTools, issues, registries, pluginFeatures }
+}
+
+export function getWidgetsForZone(
+  runtime: PluginRuntime,
+  zone: PluginWidgetZone,
+  contextOverrides?: Partial<PluginRuntimeContext>,
+): ResolvedPluginWidget[] {
+  const ctx = { ...runtime.context, ...contextOverrides }
+  return runtime.widgets.filter((w) => w.zone === zone && isWidgetVisible(w, ctx))
+}
+
+export function getDashboardWidgets(
+  runtime: PluginRuntime,
+  options: { surface: DashboardSurface; domain?: string; contextOverrides?: Partial<PluginRuntimeContext> },
+): ResolvedDashboardWidget[] {
+  const ctx = { ...runtime.context, ...options.contextOverrides }
+  return runtime.dashboardWidgets.filter((w) => {
+    const surfaces = w.surfaces ?? ['home', 'plugin-home']
+    if (!surfaces.includes(options.surface)) return false
+    if (options.domain && w.domain !== options.domain) return false
+    if (w.verticalId && ctx.tenant?.verticalId && w.verticalId !== ctx.tenant.verticalId) return false
+    if (w.permission && ctx.hasPermission && !ctx.hasPermission(w.permission)) return false
+    return true
+  })
+}
+
+const PluginRuntimeContext = React.createContext<PluginRuntime | null>(null)
+export const PluginRuntimeProvider = PluginRuntimeContext.Provider
+
+export function usePluginRuntime(): PluginRuntime {
+  return React.useContext(PluginRuntimeContext) ?? createEmptyRuntime()
+}
+
+export function usePluginRuntimeOptional(): PluginRuntime | null {
+  return React.useContext(PluginRuntimeContext)
+}

package/src/registry/index.ts

@@ -0,0 +1,163 @@
+import type { ComponentType } from 'react'
+
+// ---------------------------------------------------------------------------
+// Uniform registry — the indirection layer that lets a pure-data AppManifest
+// reference code by string id. Generalizes the entity registry pattern to
+// components, blocks, pages, metrics, scaffolds and plugins.
+//
+// Naming convention: SDK/plugin artifacts use a namespaced id
+// (`agenda.week-view`, `crud.detail-header`); app-local custom code uses the
+// reserved `custom:` prefix (`custom:tannat.HarvestBoard`). The platform never
+// generates `custom:` ids — they only come from an app's registry.tsx.
+// ---------------------------------------------------------------------------
+
+/** A JSON Schema object (loosely typed; validated by tooling, not at runtime). */
+export type JsonSchema = Record<string, unknown>
+
+export type RegistrySource = 'sdk' | 'plugin' | 'app'
+
+export interface RegistryMeta {
+  /** Human label for the platform editor. */
+  label?: string
+  description?: string
+  /** Where this artifact came from (for introspection / conflict reporting). */
+  source?: RegistrySource
+  /** Owning plugin id, when source is 'plugin'. */
+  pluginId?: string
+  /** JSON Schema for this artifact's props/config — drives the visual editor
+   *  and constrains AI generation. Optional but strongly encouraged. */
+  propsSchema?: JsonSchema
+}
+
+export interface RegistryEntry<T> {
+  id: string
+  value: T
+  meta: RegistryMeta
+}
+
+/** A typed, introspectable id→value map. Last registration wins (so an app's
+ *  registry.tsx can override an SDK artifact by re-registering its id). */
+export class Registry<T> {
+  private readonly entries = new Map<string, RegistryEntry<T>>()
+
+  constructor(readonly kind: string) {}
+
+  register(id: string, value: T, meta: RegistryMeta = {}): void {
+    this.entries.set(id, { id, value, meta })
+  }
+
+  get(id: string): T | undefined {
+    return this.entries.get(id)?.value
+  }
+
+  getEntry(id: string): RegistryEntry<T> | undefined {
+    return this.entries.get(id)
+  }
+
+  has(id: string): boolean {
+    return this.entries.has(id)
+  }
+
+  list(): RegistryEntry<T>[] {
+    return Array.from(this.entries.values())
+  }
+
+  ids(): string[] {
+    return Array.from(this.entries.keys())
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}
+
+/** True for app-local custom artifacts (`custom:*`). */
+export function isCustomId(id: string): boolean {
+  return id.startsWith('custom:')
+}
+
+// ---------------------------------------------------------------------------
+// Metric definitions (consumed by dashboard / reports / KPI panels).
+// ---------------------------------------------------------------------------
+
+export type MetricFormat = 'number' | 'currency' | 'percent' | 'duration' | 'rating'
+
+export interface MetricContext {
+  tenantId?: string
+  /** ISO date range the metric should compute over, when applicable. */
+  range?: { from: string; to: string }
+  [key: string]: unknown
+}
+
+export interface MetricValue {
+  value: number
+  previousValue?: number
+  trend?: 'up' | 'down' | 'flat'
+}
+
+export interface MetricDefinition {
+  id: string
+  label?: string
+  category?: string
+  format?: MetricFormat
+  compute: (ctx: MetricContext) => Promise<MetricValue> | MetricValue
+}
+
+// ---------------------------------------------------------------------------
+// Concrete registries. Components/blocks/pages/scaffolds hold React component
+// types; metrics hold definitions; plugins hold opaque manifests (typed at the
+// plugin layer to avoid a circular import).
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyComponent = ComponentType<any>
+
+export const componentRegistry = new Registry<AnyComponent>('component')
+export const blockRegistry = new Registry<AnyComponent>('block')
+export const pageRegistry = new Registry<AnyComponent>('page')
+export const scaffoldRegistry = new Registry<AnyComponent>('scaffold')
+export const metricRegistry = new Registry<MetricDefinition>('metric')
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const pluginRegistry = new Registry<any>('plugin')
+
+// Thin functional facade (the public API surface) -----------------------------
+
+export const registerComponent = (id: string, c: AnyComponent, meta?: RegistryMeta) =>
+  componentRegistry.register(id, c, meta)
+export const getComponent = (id: string) => componentRegistry.get(id)
+
+export const registerBlock = (id: string, c: AnyComponent, meta?: RegistryMeta) =>
+  blockRegistry.register(id, c, meta)
+export const getBlock = (id: string) => blockRegistry.get(id)
+export const listBlocks = () => blockRegistry.list()
+
+export const registerPage = (id: string, c: AnyComponent, meta?: RegistryMeta) =>
+  pageRegistry.register(id, c, meta)
+export const getPage = (id: string) => pageRegistry.get(id)
+
+export const registerScaffold = (id: string, c: AnyComponent, meta?: RegistryMeta) =>
+  scaffoldRegistry.register(id, c, meta)
+export const getScaffold = (id: string) => scaffoldRegistry.get(id)
+
+export const registerMetric = (def: MetricDefinition, meta?: RegistryMeta) =>
+  metricRegistry.register(def.id, def, meta)
+export const getMetric = (id: string) => metricRegistry.get(id)
+export const listMetrics = () => metricRegistry.list()
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const registerPlugin = (id: string, manifest: any, meta?: RegistryMeta) =>
+  pluginRegistry.register(id, manifest, meta)
+export const getPlugin = (id: string) => pluginRegistry.get(id)
+export const listPlugins = () => pluginRegistry.list()
+
+// Plugin factories — a generated app registers each installed @fayz-ai/plugin-*
+// factory by id (src/plugins.generated.ts), so a scaffold can resolve a
+// manifest's PluginRef (id + JSON config) to a live PluginManifest:
+//   getPluginFactory(ref.id)?.(ref.config)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PluginFactory = (config?: Record<string, unknown>) => any
+export const pluginFactoryRegistry = new Registry<PluginFactory>('plugin-factory')
+export const registerPluginFactory = (id: string, factory: PluginFactory, meta?: RegistryMeta) =>
+  pluginFactoryRegistry.register(id, factory, meta)
+export const getPluginFactory = (id: string) => pluginFactoryRegistry.get(id)
+export const listPluginFactories = () => pluginFactoryRegistry.list()

package/src/router/index.ts

@@ -0,0 +1,29 @@
+export interface RouterAdapter {
+  navigate(to: string): void
+  getCurrentPath(): string
+  onPathChange(cb: (path: string) => void): () => void
+}
+
+export function hashRouterAdapter(): RouterAdapter {
+  return {
+    navigate(to) { window.location.hash = to },
+    getCurrentPath() { return window.location.hash.slice(1) || '/' },
+    onPathChange(cb) {
+      const handler = () => cb(window.location.hash.slice(1) || '/')
+      window.addEventListener('hashchange', handler)
+      return () => window.removeEventListener('hashchange', handler)
+    },
+  }
+}
+
+export function windowRouterAdapter(): RouterAdapter {
+  return {
+    navigate(to) { window.history.pushState(null, '', to) },
+    getCurrentPath() { return window.location.pathname },
+    onPathChange(cb) {
+      const handler = () => cb(window.location.pathname)
+      window.addEventListener('popstate', handler)
+      return () => window.removeEventListener('popstate', handler)
+    },
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,15 @@
+export {
+  createFayzRuntimeClient,
+  FayzRuntimeError,
+} from '@fayz-ai/sdk/runtime'
+export type {
+  FayzRuntimeClientOptions,
+  FayzRuntimeEnvironment,
+  GoogleCalendarEvent,
+  GoogleCalendarEventInput,
+  GoogleCalendarEventTime,
+  ListGoogleCalendarEventsInput,
+  PluginOAuthExchangeInput,
+  PluginOAuthExchangeResponse,
+  RuntimePluginOAuthGrant,
+} from '@fayz-ai/sdk/runtime'