@astrale-os/sdk 0.1.9 → 0.2.0

package/src/domain/extend-core.ts

@@ -1,287 +0,0 @@
-/**
- * Build an augmented `Core<S>` that includes auto-materialized View and
- * standalone-function nodes (one per entry in `defineRemoteDomain`'s `views` /
- * `remoteFunctions` config), plus their parent Folder + optional `view_for`
- * edges. Returns the resolved effective bindings alongside so callers don't
- * recompute them.
- *
- * Standalone callables (the former `RemoteFunction` class) are materialized as
- * the canonical kernel `Function` node class — "remote" is just a `binding`,
- * not a distinct kind, so there is no per-domain class to configure.
- *
- * Conflicts: if the user core already declares a top-level node at
- * `<viewsFolder>` or `<functionsFolder>`, throws — the auto-materialization
- * reserves those slugs.
- */
-
-import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type {
-  AnyEdgeDef,
-  AnyNodeDef,
-  Core,
-  CoreEdgeEntry,
-  CoreNodeEntry,
-  Schema,
-} from '@astrale-os/kernel-dsl'
-
-import { Folder, K, KernelSchema } from '@astrale-os/kernel-core'
-import { buildCorePath } from '@astrale-os/kernel-dsl'
-
-/** Canonical node class for standalone callables (the former `RemoteFunction`). */
-const FUNCTION_CLASS = KernelSchema.classes.Function as unknown as AnyNodeDef
-/** Canonical node class for GUI views. */
-const VIEW_CLASS = KernelSchema.classes.View as unknown as AnyNodeDef
-/** Canonical edge class linking a View to its target. */
-const VIEW_FOR_EDGE_CLASS = KernelSchema.classes.view_for as unknown as AnyEdgeDef
-
-import type { AnyRemoteFunctionDef } from '../define/remote-function'
-import type { ViewDef } from '../define/view'
-
-export const DEFAULT_VIEWS_FOLDER = 'views'
-export const DEFAULT_FUNCTIONS_FOLDER = 'functions'
-const SLUG_RE = /^[a-z][a-z0-9-]*$/
-
-export type ExtendCoreConfig = {
-  schema: Schema
-  origin: string
-  userCore?: Core
-  /**
-   * The worker's serving URL — the base every auto-materialized binding
-   * resolves against. OMITTED at define time (the URL is known only to the
-   * spec producers): the aux nodes then materialize structure-only (paths,
-   * names, refs — what identity/subs resolution needs) with no `binding`
-   * stamped and empty binding maps. Every install graph comes from a
-   * `materializeRemoteDomain(domain, url)` call where it is present.
-   */
-  url?: string
-
-  viewClass?: AnyNodeDef
-  viewForEdgeClass?: AnyEdgeDef
-  viewsFolder?: string
-  // oxlint-disable-next-line no-explicit-any
-  views?: Record<string, ViewDef<any>>
-
-  functionsFolder?: string
-  remoteFunctions?: Record<string, AnyRemoteFunctionDef>
-}
-
-export type ExtendCoreResult = {
-  core: Core
-  viewBindings: Record<string, FunctionBinding>
-  remoteFunctionBindings: Record<string, FunctionBinding>
-}
-
-export function extendCore(config: ExtendCoreConfig): ExtendCoreResult {
-  const {
-    schema,
-    origin,
-    userCore,
-    url,
-    viewClass = VIEW_CLASS,
-    viewForEdgeClass = VIEW_FOR_EDGE_CLASS,
-    viewsFolder = DEFAULT_VIEWS_FOLDER,
-    views,
-    functionsFolder = DEFAULT_FUNCTIONS_FOLDER,
-    remoteFunctions,
-  } = config
-
-  validateInputs(config)
-
-  const nodes: CoreNodeEntry[] = userCore ? [...userCore.__nodes] : []
-  const edges: CoreEdgeEntry[] = userCore ? [...userCore.__edges] : []
-  const viewBindings: Record<string, FunctionBinding> = {}
-  const remoteFunctionBindings: Record<string, FunctionBinding> = {}
-
-  if (views && viewClass) {
-    // Enforce ViewDef's documented exclusivity: `mount` (SPA route) cannot be
-    // combined with `render` (inline HTML handler) or an explicit `binding` —
-    // silently ignoring one of them would deploy a view that behaves
-    // differently than its definition reads.
-    for (const [slug, def] of Object.entries(views)) {
-      if (def.mount && (def.render || def.binding)) {
-        throw new Error(
-          `defineRemoteDomain: view "${slug}" sets \`mount\` together with ` +
-            `${def.render ? '`render`' : '`binding`'} — they are mutually exclusive.`,
-        )
-      }
-    }
-    assertNoConflict(nodes, origin, viewsFolder)
-    addFolderAndEntries({
-      origin,
-      folderSlug: viewsFolder,
-      nodes,
-      entries: Object.entries(views).map(([slug, def]) => {
-        const binding = url
-          ? def.mount
-            ? { remoteUrl: joinWorkerPath(url, def.mount) }
-            : resolveBinding(def.binding, url, viewsFolder, slug)
-          : undefined
-        if (binding) viewBindings[slug] = binding
-        return {
-          slug,
-          nodeClass: viewClass,
-          data: buildFunctionData(slug, binding),
-          edges: buildViewForEdges(slug, def, viewForEdgeClass, viewsFolder, origin),
-        }
-      }),
-      edges,
-    })
-  }
-
-  if (remoteFunctions) {
-    assertNoConflict(nodes, origin, functionsFolder)
-    addFolderAndEntries({
-      origin,
-      folderSlug: functionsFolder,
-      nodes,
-      entries: Object.entries(remoteFunctions).map(([slug, def]) => {
-        const binding = url ? resolveBinding(def.binding, url, functionsFolder, slug) : undefined
-        if (binding) remoteFunctionBindings[slug] = binding
-        return {
-          slug,
-          // Standalone callables materialize as the canonical kernel Function class.
-          nodeClass: FUNCTION_CLASS,
-          data: {
-            ...buildFunctionData(slug, binding),
-            [K.$.i('Function').ref.key]: def.ref ?? `function.${slug}`,
-          },
-          edges: [],
-        }
-      }),
-      edges,
-    })
-  }
-
-  return {
-    core: { schema, domain: origin, __nodes: nodes, __edges: edges },
-    viewBindings,
-    remoteFunctionBindings,
-  }
-}
-
-/** Join a worker-relative mount path onto the serving url (single slash). */
-function joinWorkerPath(url: string, mount: string): string {
-  const base = url.replace(/\/+$/, '')
-  return `${base}/${mount.replace(/^\/+/, '')}`
-}
-
-export function resolveBinding(
-  override: FunctionBinding | undefined,
-  url: string,
-  folderSlug: string,
-  slug: string,
-): FunctionBinding {
-  // Same trailing-slash discipline as `joinWorkerPath` — a `url` ending in `/`
-  // must not produce `//` in the binding (the kernel pins iss by exact string).
-  const base = url.replace(/\/+$/, '')
-  if (override) {
-    return {
-      ...override,
-      remoteUrl: override.remoteUrl ?? `${base}/${folderSlug}/${slug}`,
-    }
-  }
-  return { remoteUrl: `${base}/${folderSlug}/${slug}` }
-}
-
-// ── Internal ───────────────────────────────────────────────────────────────
-
-function validateInputs(config: ExtendCoreConfig): void {
-  if (config.views) {
-    for (const slug of Object.keys(config.views)) {
-      if (!SLUG_RE.test(slug)) {
-        throw new Error(`defineRemoteDomain: invalid view slug "${slug}" — must match ${SLUG_RE}.`)
-      }
-    }
-  }
-  if (config.remoteFunctions) {
-    for (const slug of Object.keys(config.remoteFunctions)) {
-      if (!SLUG_RE.test(slug)) {
-        throw new Error(
-          `defineRemoteDomain: invalid remote-function slug "${slug}" — must match ${SLUG_RE}.`,
-        )
-      }
-    }
-  }
-}
-
-function assertNoConflict(
-  nodes: readonly CoreNodeEntry[],
-  origin: string,
-  folderSlug: string,
-): void {
-  const folderPath = buildCorePath(origin, [folderSlug])
-  if (nodes.some((n) => n.path === folderPath)) {
-    throw new Error(
-      `defineRemoteDomain: top-level core slug "${folderSlug}" is reserved by ` +
-        'SDK auto-materialization. Move the conflicting node or rename the ' +
-        '`viewsFolder` / `functionsFolder` config.',
-    )
-  }
-}
-
-type EntryDescriptor = {
-  slug: string
-  nodeClass: AnyNodeDef
-  data: Record<string, unknown>
-  edges: CoreEdgeEntry[]
-}
-
-function addFolderAndEntries(args: {
-  origin: string
-  folderSlug: string
-  entries: EntryDescriptor[]
-  nodes: CoreNodeEntry[]
-  edges: CoreEdgeEntry[]
-}): void {
-  const { origin, folderSlug, entries, nodes, edges } = args
-
-  const folderPath = buildCorePath(origin, [folderSlug])
-  nodes.push({
-    path: folderPath,
-    def: Folder as unknown as AnyNodeDef,
-    data: { [K.Named.name.key]: folderSlug },
-  })
-
-  for (const entry of entries) {
-    nodes.push({
-      path: buildCorePath(origin, [folderSlug, entry.slug]),
-      def: entry.nodeClass,
-      data: entry.data,
-      parent: folderPath,
-    })
-    for (const e of entry.edges) edges.push(e)
-  }
-}
-
-function buildFunctionData(
-  slug: string,
-  binding: FunctionBinding | undefined,
-): Record<string, unknown> {
-  // Match the kernel-core schema serializer which JSON-stringifies the
-  // `Function.binding` value on Function nodes (see
-  // kernel/core/domain/serialize/schema.ts). The kernel install validator
-  // checks `typeof binding === 'string'` then parses; storing a raw object
-  // trips the validator with "missing remote binding" even when the object IS
-  // the binding. No binding at all (define-time, no url) → no prop stamped.
-  return {
-    [K.Named.name.key]: slug,
-    ...(binding ? { [K.$.i('Function').binding.key]: JSON.stringify(binding) } : {}),
-  }
-}
-
-function buildViewForEdges(
-  slug: string,
-  def: ViewDef,
-  edgeClass: AnyEdgeDef | undefined,
-  viewsFolder: string,
-  origin: string,
-): CoreEdgeEntry[] {
-  if (!def.viewFor || !edgeClass) return []
-  const targets = Array.isArray(def.viewFor) ? def.viewFor : [def.viewFor]
-  const from = buildCorePath(origin, [viewsFolder, slug])
-  return targets.map((target) => ({
-    from,
-    edge: edgeClass,
-    to: target as CoreEdgeEntry['to'],
-  }))
-}