@bespokeagentics/microdots-host 0.1.0 → 0.1.2

package/src/composeFromSelection.ts

@@ -0,0 +1,376 @@
+import type { CatalogLockV1 } from '@bespokeagentics/microdots-authoring'
+import type {
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import {
+  type CompositionIssue,
+  type CompositionSpec,
+  type CompositionSpecV2,
+  migrateCompositionSpecV1,
+  validateComposition,
+} from './compositionSpec.ts'
+import { FillCompositionError } from './fillComposition.ts'
+import { type SlotKind } from './slots.ts'
+import {
+  type HostTopology,
+  type TopologyPlacement,
+  type TopologyRoute,
+  type Wire,
+  type WireValueType,
+} from './wire.ts'
+
+/**
+ * Layout of catalogued tags in the topology. `together` is one route with
+ * every selected tag; `per-tag` is one route per tag. Both are closed over
+ * the catalog — a tag that is not a surface cannot be represented.
+ */
+export type CompositionLayout = 'together' | 'per-tag'
+
+export type CompositionWirePick = {
+  readonly from: string
+  readonly event: string
+  readonly field: string
+  readonly to: string
+  readonly input: string
+}
+
+export type ComposeFromSelectionInput = {
+  readonly brief?: string
+  readonly hostId: string
+  readonly hostLabel: string
+  readonly tags: ReadonlyArray<string>
+  readonly layout: CompositionLayout
+  readonly slotKind: SlotKind
+  readonly wires: ReadonlyArray<CompositionWirePick>
+}
+
+const THEME: { readonly name: string; readonly version: string } = {
+  name: '@bespokeagentics/microdots-theme',
+  version: '0.1.1',
+}
+
+const ALL_ENVS: Wire['envs'] = ['dev', 'preview', 'prod']
+
+const issue = (path: string, message: string): CompositionIssue => ({
+  path,
+  message,
+})
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const propertiesOf = (
+  jsonSchema: unknown,
+): Readonly<Record<string, unknown>> | undefined => {
+  if (!isRecord(jsonSchema)) {
+    return undefined
+  }
+  const nested = jsonSchema['schema']
+  if (isRecord(nested) && isRecord(nested['properties'])) {
+    return nested['properties']
+  }
+  if (isRecord(jsonSchema['properties'])) {
+    return jsonSchema['properties']
+  }
+  return undefined
+}
+
+const jsonTypeOf = (spec: unknown): WireValueType => {
+  if (!isRecord(spec)) {
+    return 'string'
+  }
+  const declared = spec['type']
+  if (declared === 'number' || declared === 'integer') {
+    return 'number'
+  }
+  if (declared === 'boolean') {
+    return 'boolean'
+  }
+  if (declared === 'object' || declared === 'array') {
+    return 'json'
+  }
+  return 'string'
+}
+
+/** Payload field names a picker can offer for this event. */
+export const eventFieldsOf = (
+  event: ManifestEvent,
+): ReadonlyArray<{ readonly name: string; readonly type: WireValueType }> => {
+  const properties = propertiesOf(event.payload.jsonSchema)
+  if (properties === undefined) {
+    return []
+  }
+  return Object.entries(properties).map(([name, spec]) => ({
+    name,
+    type: jsonTypeOf(spec),
+  }))
+}
+
+/** Attributes a wire may target — environment attrs are host-owned. */
+export const wireableAttributesOf = (
+  surface: ManifestTag,
+): ManifestTag['attributes'] =>
+  surface.attributes.filter(attribute => attribute.ownership !== 'environment')
+
+const uniqueTags = (tags: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const seen = new Set<string>()
+  const ordered: Array<string> = []
+  for (const tag of tags) {
+    if (seen.has(tag)) {
+      continue
+    }
+    seen.add(tag)
+    ordered.push(tag)
+  }
+  return ordered
+}
+
+const titleCase = (tag: string): string =>
+  tag
+    .split('-')
+    .filter(part => part.length > 0)
+    .map(part => {
+      const head = part.slice(0, 1)
+      const tail = part.slice(1)
+      return `${head.toUpperCase()}${tail}`
+    })
+    .join(' ')
+
+const slotIdFor = (tag: string): string => `${tag}-slot`
+
+const surfaceMap = (
+  surfaces: ReadonlyArray<ManifestTag>,
+): ReadonlyMap<string, ManifestTag> => {
+  const map = new Map<string, ManifestTag>()
+  for (const surface of surfaces) {
+    map.set(surface.tag, surface)
+  }
+  return map
+}
+
+const placement = (tag: string, order: number): TopologyPlacement => ({
+  tag,
+  slotId: slotIdFor(tag),
+  order,
+})
+
+const routeTogether = (tags: ReadonlyArray<string>): TopologyRoute => ({
+  path: '/',
+  label: 'Home',
+  title: 'Home',
+  sectionIds: ['section-home'],
+  mounts: tags.map((tag, index) => placement(tag, index)),
+})
+
+const routeForTag = (tag: string): TopologyRoute => {
+  const label = titleCase(tag)
+  return {
+    path: `/${tag}`,
+    label,
+    title: label,
+    sectionIds: [`section-${tag}`],
+    mounts: [placement(tag, 0)],
+  }
+}
+
+const resolveTags = (
+  tags: ReadonlyArray<string>,
+  catalog: ReadonlyMap<string, ManifestTag>,
+): {
+  readonly tags: ReadonlyArray<string>
+  readonly issues: ReadonlyArray<CompositionIssue>
+} => {
+  const unique = uniqueTags(tags)
+  const issues: Array<CompositionIssue> = []
+  if (unique.length === 0) {
+    issues.push(issue('tags', 'Pick at least one MicroDot from the catalog.'))
+  }
+  for (const [index, tag] of unique.entries()) {
+    if (!catalog.has(tag)) {
+      issues.push(
+        issue(
+          `tags[${index.toString()}]`,
+          `"${tag}" is not in the catalog. Pick from the chips.`,
+        ),
+      )
+    }
+  }
+  return { tags: unique, issues }
+}
+
+const resolveWires = (
+  picks: ReadonlyArray<CompositionWirePick>,
+  selected: ReadonlySet<string>,
+  catalog: ReadonlyMap<string, ManifestTag>,
+): {
+  readonly wires: ReadonlyArray<Wire>
+  readonly issues: ReadonlyArray<CompositionIssue>
+} => {
+  const wires: Array<Wire> = []
+  const issues: Array<CompositionIssue> = []
+  for (const [index, pick] of picks.entries()) {
+    const path = `wires[${index.toString()}]`
+    if (!selected.has(pick.from)) {
+      issues.push(
+        issue(
+          `${path}.from`,
+          `"${pick.from}" is not one of the selected MicroDots.`,
+        ),
+      )
+      continue
+    }
+    if (!selected.has(pick.to)) {
+      issues.push(
+        issue(
+          `${path}.to`,
+          `"${pick.to}" is not one of the selected MicroDots.`,
+        ),
+      )
+      continue
+    }
+    const fromSurface = catalog.get(pick.from)
+    const toSurface = catalog.get(pick.to)
+    if (fromSurface === undefined || toSurface === undefined) {
+      continue
+    }
+    const event = fromSurface.events.find(
+      candidate => candidate.name === pick.event,
+    )
+    if (event === undefined) {
+      issues.push(
+        issue(`${path}.event`, `"${pick.from}" has no event "${pick.event}".`),
+      )
+      continue
+    }
+    const field = eventFieldsOf(event).find(
+      candidate => candidate.name === pick.field,
+    )
+    if (field === undefined) {
+      issues.push(
+        issue(
+          `${path}.field`,
+          `event "${pick.event}" has no field "${pick.field}".`,
+        ),
+      )
+      continue
+    }
+    const input = wireableAttributesOf(toSurface).find(
+      candidate => candidate.name === pick.input,
+    )
+    if (input === undefined) {
+      issues.push(
+        issue(
+          `${path}.input`,
+          `"${pick.to}" has no wireable input "${pick.input}".`,
+        ),
+      )
+      continue
+    }
+    wires.push({
+      id: `w${(index + 1).toString()}`,
+      from: pick.from,
+      event: pick.event,
+      field: pick.field,
+      fieldType: field.type,
+      to: pick.to,
+      input: pick.input,
+      inputType: input.type,
+      transform: { _tag: 'direct' },
+      envs: ALL_ENVS,
+      plain: `When ${pick.event} on ${pick.from}, set ${pick.input} on ${pick.to}.`,
+    })
+  }
+  return { wires, issues }
+}
+
+/**
+ * Build a CompositionSpec from a catalog picker. `generate[]` is always
+ * empty: unknown tags cannot be introduced here. Fail closed if a pick is
+ * not a catalogued surface, event, field, or wireable attribute.
+ */
+export const composeFromSelection = (
+  input: ComposeFromSelectionInput,
+  surfaces: ReadonlyArray<ManifestTag>,
+): CompositionSpec => {
+  const catalog = surfaceMap(surfaces)
+  const resolved = resolveTags(input.tags, catalog)
+  const selected = new Set(resolved.tags)
+  const wired = resolveWires(input.wires, selected, catalog)
+  const issues = [...resolved.issues, ...wired.issues]
+  if (issues.length > 0) {
+    throw new FillCompositionError({ _tag: 'invalid', issues })
+  }
+
+  const tags = resolved.tags
+  const first = tags[0]
+  if (first === undefined) {
+    throw new FillCompositionError({
+      _tag: 'invalid',
+      issues: [issue('tags', 'Pick at least one MicroDot from the catalog.')],
+    })
+  }
+
+  const routes: readonly [TopologyRoute, ...Array<TopologyRoute>] =
+    input.layout === 'together'
+      ? [routeTogether(tags)]
+      : [routeForTag(first), ...tags.slice(1).map(routeForTag)]
+
+  const topology: HostTopology = {
+    host: {
+      id: input.hostId,
+      label: input.hostLabel,
+      ownedInputs: [],
+    },
+    routes,
+    slotManifest: {
+      theme: THEME,
+      slots: tags.map((tag, index) => ({
+        id: slotIdFor(tag),
+        kind: input.slotKind,
+        row: input.layout === 'together' ? 1 : index + 1,
+        capacity: 1,
+      })),
+    },
+    wires: [...wired.wires],
+    watch: [],
+  }
+
+  const trimmed = input.brief?.trim() ?? ''
+  const spec: CompositionSpec = {
+    schemaVersion: 1,
+    generate: [],
+    topology,
+    ...(trimmed.length > 0 ? { brief: trimmed } : {}),
+  }
+
+  const lint = validateComposition(spec, surfaces)
+  if (lint.length > 0) {
+    throw new FillCompositionError({ _tag: 'invalid', issues: lint })
+  }
+  return spec
+}
+
+/**
+ * Current write-side adapter for the existing-surface lane. The picker remains
+ * topology-only, so its established v1 result has the one lossless migration:
+ * attach the service-owned catalog lock and emit v2. Legacy callers may still
+ * call `composeFromSelection` while saved v1 data is being read.
+ */
+export const composeExistingSurfacesFromSelection = (
+  input: ComposeFromSelectionInput,
+  surfaces: ReadonlyArray<ManifestTag>,
+  catalogLock: CatalogLockV1,
+): CompositionSpecV2 => {
+  const result = migrateCompositionSpecV1(
+    composeFromSelection(input, surfaces),
+    catalogLock,
+  )
+  if (result._tag === 'migrated') {
+    return result.value
+  }
+  throw new Error(
+    'topology-only existing-surface composition unexpectedly required migration input',
+  )
+}

package/src/compositionSpec.test.ts

@@ -0,0 +1,311 @@
+import { Schema as S } from 'effect'
+import { describe, expect, test } from 'vitest'
+
+import type {
+  ManifestAttribute,
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import {
+  type CompositionSpec,
+  compositionJsonSchema,
+  decodeCompositionSpecSync,
+  encodeTopologyJson,
+  schemaEventsFor,
+  schemaInputsFor,
+  validateComposition,
+} from './compositionSpec.ts'
+import { HostTopology, type TopologyRoute, type Wire } from './wire.ts'
+
+const attribute = (
+  name: string,
+  type: ManifestAttribute['type'] = 'string',
+): ManifestAttribute => ({
+  name,
+  type,
+  required: false,
+  live: true,
+  ownership: 'dot',
+})
+
+const manifestEvent = (
+  name: string,
+  properties: Readonly<Record<string, unknown>>,
+): ManifestEvent => ({
+  name,
+  payload: {
+    ref: `@microdots/test/contract#${name}`,
+    jsonSchema: {
+      dialect: 'draft-2020-12',
+      schema: { type: 'object', properties },
+      definitions: {},
+    },
+  },
+})
+
+const PRICE: ManifestTag = {
+  tag: 'readout-view',
+  attributes: [attribute('symbol')],
+  events: [manifestEvent('quote-changed', { symbol: { type: 'string' } })],
+}
+
+const FLEET: ManifestTag = {
+  tag: 'fleet-health',
+  attributes: [attribute('region')],
+  events: [],
+}
+
+const SURFACES: ReadonlyArray<ManifestTag> = [PRICE, FLEET]
+
+const route = (path: string, tag: string, slotId: string): TopologyRoute => ({
+  path,
+  label: path,
+  title: path,
+  sectionIds: [`section-${tag}`],
+  mounts: [{ tag, slotId }],
+})
+
+const lookupWire: Wire = {
+  id: 'w1',
+  from: 'readout-view',
+  event: 'quote-changed',
+  field: 'symbol',
+  fieldType: 'string',
+  to: 'fleet-health',
+  input: 'region',
+  inputType: 'string',
+  transform: {
+    _tag: 'lookup',
+    rows: { FOLD: 'us-east' },
+    fallback: 'us-east',
+  },
+  envs: ['dev', 'preview', 'prod'],
+  plain:
+    "When the ticker's quote changes, set the fleet widget's region to the region that trades that symbol.",
+}
+
+const topologyOf = (wires: ReadonlyArray<Wire>): HostTopology => ({
+  host: { id: 'demo-host', label: 'Demo', ownedInputs: [] },
+  routes: [
+    route('/price', 'readout-view', 'price-slot'),
+    route('/fleet', 'fleet-health', 'fleet-slot'),
+  ],
+  slotManifest: {
+    theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.0' },
+    slots: [
+      { id: 'price-slot', kind: 'band', row: 1, capacity: 1 },
+      { id: 'fleet-slot', kind: 'band', row: 1, capacity: 1 },
+    ],
+  },
+  wires,
+  watch: [],
+})
+
+const specOf = (
+  topology: HostTopology,
+  generate: CompositionSpec['generate'] = [],
+): CompositionSpec => ({
+  schemaVersion: 1,
+  generate,
+  topology,
+})
+
+describe('CompositionSpec', () => {
+  test('decodes a reuse-only composition', () => {
+    const spec = specOf(topologyOf([lookupWire]))
+    expect(decodeCompositionSpecSync(spec)).toEqual(spec)
+  })
+
+  test('rejects a slug that is not lower-kebab', () => {
+    expect(() =>
+      decodeCompositionSpecSync(
+        specOf(topologyOf([]), [
+          { slug: 'Nope', tag: 'nope-panel', port: 3990 },
+        ]),
+      ),
+    ).toThrow()
+  })
+
+  test('rejects a generated app that claims a reference identity', () => {
+    expect(() =>
+      decodeCompositionSpecSync(
+        specOf(topologyOf([]), [
+          { slug: 'dossier', tag: 'dossier-panel', port: 3990 },
+        ]),
+      ),
+    ).toThrow()
+  })
+})
+
+describe('validateComposition', () => {
+  test('accepts the price→fleet lookup against catalogued surfaces', () => {
+    expect(
+      validateComposition(specOf(topologyOf([lookupWire])), SURFACES),
+    ).toEqual([])
+  })
+
+  test('rejects a wire whose event does not exist on the from tag', () => {
+    const bogus: Wire = { ...lookupWire, event: 'bid-placed' }
+    const issues = validateComposition(specOf(topologyOf([bogus])), SURFACES)
+    expect(issues).toEqual([
+      {
+        path: 'topology.wires[0]',
+        message:
+          'wire "w1" derives draft — a tag, event, field, input or type pairing is missing from the surface catalog',
+      },
+    ])
+  })
+
+  test('rejects a mount tag that is neither catalogued nor generated', () => {
+    const topology = topologyOf([])
+    const extra: HostTopology = {
+      ...topology,
+      routes: [
+        ...topology.routes,
+        route('/ghost', 'ghost-panel', 'price-slot'),
+      ],
+    }
+    const issues = validateComposition(specOf(extra), SURFACES)
+    expect(issues).toContainEqual({
+      path: 'topology.routes[2].mounts[0].tag',
+      message:
+        'tag "ghost-panel" is neither a catalogued surface nor in generate[]',
+    })
+  })
+
+  test('rejects a slot id the slot manifest does not declare', () => {
+    const topology = topologyOf([])
+    const first = topology.routes[0]
+    if (first === undefined) {
+      throw new Error('fixture routes are non-empty')
+    }
+    const broken: HostTopology = {
+      ...topology,
+      routes: [
+        {
+          ...first,
+          mounts: [{ tag: 'readout-view', slotId: 'missing-slot' }],
+        },
+        ...topology.routes.slice(1),
+      ],
+    }
+    const issues = validateComposition(specOf(broken), SURFACES)
+    expect(issues).toContainEqual({
+      path: 'topology.routes[0].mounts[0].slotId',
+      message: 'slot "missing-slot" is not in topology.slotManifest',
+    })
+  })
+
+  test('rejects a generated tag that is never placed', () => {
+    const issues = validateComposition(
+      specOf(topologyOf([lookupWire]), [
+        { slug: 'inventory', tag: 'inventory-panel', port: 3991 },
+      ]),
+      SURFACES,
+    )
+    expect(issues).toContainEqual({
+      path: 'generate[0].tag',
+      message:
+        'generated tag "inventory-panel" is never placed in the topology',
+    })
+  })
+
+  test('skips draft checks for wires that touch a generate[] tag', () => {
+    const generated: Wire = {
+      ...lookupWire,
+      id: 'w-new',
+      to: 'inventory-panel',
+      input: 'refresh-token',
+    }
+    const topology = topologyOf([generated])
+    const withSlot: HostTopology = {
+      ...topology,
+      slotManifest: {
+        theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.0' },
+        slots: [
+          ...(topology.slotManifest?.slots ?? []),
+          { id: 'inventory-slot', kind: 'band', row: 2, capacity: 1 },
+        ],
+      },
+      routes: [
+        ...topology.routes,
+        route('/inventory', 'inventory-panel', 'inventory-slot'),
+      ],
+    }
+    expect(
+      validateComposition(
+        specOf(withSlot, [
+          { slug: 'inventory', tag: 'inventory-panel', port: 3991 },
+        ]),
+        SURFACES,
+      ),
+    ).toEqual([])
+  })
+
+  test('rejects duplicate generate slugs', () => {
+    const topology = topologyOf([])
+    const withSlots: HostTopology = {
+      ...topology,
+      slotManifest: {
+        theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.0' },
+        slots: [
+          ...(topology.slotManifest?.slots ?? []),
+          { id: 'a-slot', kind: 'band', row: 2, capacity: 1 },
+          { id: 'b-slot', kind: 'band', row: 3, capacity: 1 },
+        ],
+      },
+      routes: [
+        ...topology.routes,
+        route('/a', 'a-panel', 'a-slot'),
+        route('/b', 'b-panel', 'b-slot'),
+      ],
+    }
+    const issues = validateComposition(
+      specOf(withSlots, [
+        { slug: 'same', tag: 'a-panel', port: 3991 },
+        { slug: 'same', tag: 'b-panel', port: 3992 },
+      ]),
+      SURFACES,
+    )
+    expect(issues).toContainEqual({
+      path: 'generate[1].slug',
+      message: 'slug "same" duplicates generate[0]',
+    })
+  })
+})
+
+describe('compositionJsonSchema', () => {
+  test('admits quote-changed on readout-view and not bid-placed', () => {
+    const schema = compositionJsonSchema(SURFACES)
+    expect(schemaEventsFor(schema, 'readout-view')).toEqual(['quote-changed'])
+    expect(schemaEventsFor(schema, 'readout-view')).not.toContain('bid-placed')
+    expect(schemaInputsFor(schema, 'fleet-health')).toEqual(['region'])
+  })
+
+  test('closes the transform vocabulary to the three tags that exist', () => {
+    const schema = compositionJsonSchema(SURFACES)
+    const wires = schema.properties?.['topology']?.properties?.['wires']?.items
+    const base = wires?.allOf?.[0] ?? wires
+    const transform = base?.properties?.['transform']
+    const tags = (transform?.oneOf ?? []).map(
+      variant => variant.properties?.['_tag']?.const,
+    )
+    expect(tags).toEqual(['direct', 'lookup', 'condition'])
+  })
+
+  test('lists legal tags, events, attrs and transforms in $comment so the schema is the prompt', () => {
+    const schema = compositionJsonSchema(SURFACES)
+    expect(schema.$comment).toContain('ManifestTag')
+    expect(schema.properties?.['schemaVersion']?.const).toBe(1)
+  })
+})
+
+describe('encodeTopologyJson', () => {
+  test('round-trips through JSON and HostTopology', () => {
+    const topology = topologyOf([lookupWire])
+    const json = encodeTopologyJson(topology)
+    const decoded = S.decodeSync(S.fromJsonString(HostTopology))(json)
+    expect(decoded).toEqual(topology)
+  })
+})