@bespokeagentics/create-microdots-host 0.1.0

package/templates/base/microdots/pulse/src/app.ts

@@ -0,0 +1,275 @@
+import { Duration, Effect, Schema as S, Stream } from 'effect'
+import { Command, Port, Subscription } from 'foldkit'
+import type { Html, HtmlBuilder } from 'foldkit/html'
+import { m } from 'foldkit/message'
+import { makeElement } from 'foldkit/runtime'
+import { ts } from 'foldkit/schema'
+
+import { PulseClient, pulseClientLive } from './client.ts'
+import { Heartbeat, HeartbeatObserved } from './contract.ts'
+
+export const POLL_INTERVAL_MS = 5_000
+
+const Loading = ts('Loading')
+const Ready = ts('Ready', { value: Heartbeat, stale: S.Boolean })
+const Failed = ts('Failed', { error: S.String, last: S.UndefinedOr(Heartbeat) })
+const Unauthorized = ts('Unauthorized')
+const RemoteHeartbeat = S.Union([Loading, Ready, Failed, Unauthorized])
+type RemoteHeartbeat = typeof RemoteHeartbeat.Type
+
+const Model = S.Struct({
+  heartbeat: RemoteHeartbeat,
+  scopeId: S.String,
+  apiUrl: S.String,
+  pollIntervalMs: S.Number,
+  polls: S.Number,
+})
+type Model = typeof Model.Type
+
+const PollTicked = m('PollTicked')
+const HeartbeatReceived = m('HeartbeatReceived', { heartbeat: Heartbeat })
+const HeartbeatFailed = m('HeartbeatFailed', { error: S.String })
+const HeartbeatPublished = m('HeartbeatPublished')
+const ScopeChanged = m('ScopeChanged', { scopeId: S.String })
+const RefreshRequested = m('RefreshRequested')
+const Message = S.Union([
+  PollTicked,
+  HeartbeatReceived,
+  HeartbeatFailed,
+  HeartbeatPublished,
+  ScopeChanged,
+  RefreshRequested,
+])
+type Message = typeof Message.Type
+
+export const ports = {
+  inbound: { scopeChanged: Port.inbound(S.String) },
+  outbound: { heartbeatObserved: Port.outbound(HeartbeatObserved) },
+}
+
+const FetchHeartbeat = Command.define('FetchHeartbeat', {
+  args: { scopeId: S.String },
+  messages: [HeartbeatReceived, HeartbeatFailed],
+  execute: ({ scopeId }) =>
+    Effect.gen(function* () {
+      const client = yield* PulseClient
+      const heartbeat = yield* client.GetHeartbeat({ scopeId })
+      return HeartbeatReceived({ heartbeat })
+    }).pipe(
+      Effect.catch(error =>
+        Effect.succeed(
+          HeartbeatFailed({
+            error:
+              error._tag === 'HeartbeatUnavailable'
+                ? error.reason
+                : `could not reach the service (${error._tag})`,
+          }),
+        ),
+      ),
+    ),
+})
+
+const PublishHeartbeat = Command.define('PublishHeartbeat', {
+  args: { id: S.String, sequence: S.Number, scopeId: S.String },
+  messages: [HeartbeatPublished],
+  execute: payload =>
+    Port.emit(ports.outbound.heartbeatObserved, payload).pipe(
+      Effect.as(HeartbeatPublished()),
+    ),
+})
+
+const refreshing = (remote: RemoteHeartbeat): RemoteHeartbeat =>
+  remote._tag === 'Ready' ? Ready({ value: remote.value, stale: true }) : remote
+
+const lastGood = (remote: RemoteHeartbeat): Heartbeat | undefined =>
+  remote._tag === 'Ready'
+    ? remote.value
+    : remote._tag === 'Failed'
+      ? remote.last
+      : undefined
+
+type UpdateResult = readonly [
+  Model,
+  ReadonlyArray<Command.Command<Message, never, PulseClient>>,
+]
+
+const update = (model: Model, message: Message): UpdateResult => {
+  switch (message._tag) {
+    case 'PollTicked':
+    case 'RefreshRequested':
+      return [
+        { ...model, heartbeat: refreshing(model.heartbeat) },
+        [FetchHeartbeat({ scopeId: model.scopeId })],
+      ]
+    case 'HeartbeatReceived':
+      return [
+        {
+          ...model,
+          heartbeat: Ready({ value: message.heartbeat, stale: false }),
+          polls: model.polls + 1,
+        },
+        [
+          PublishHeartbeat({
+            id: message.heartbeat.id,
+            sequence: message.heartbeat.sequence,
+            scopeId: message.heartbeat.scopeId,
+          }),
+        ],
+      ]
+    case 'HeartbeatFailed':
+      return [
+        {
+          ...model,
+          heartbeat: Failed({
+            error: message.error,
+            last: lastGood(model.heartbeat),
+          }),
+        },
+        [],
+      ]
+    case 'ScopeChanged':
+      return [
+        {
+          ...model,
+          scopeId: message.scopeId,
+          heartbeat: refreshing(model.heartbeat),
+        },
+        [FetchHeartbeat({ scopeId: message.scopeId })],
+      ]
+    case 'HeartbeatPublished':
+      return [model, []]
+  }
+}
+
+const subscriptions = Subscription.make<Model, Message, PulseClient>()(
+  entry => ({
+    poll: entry(
+      { pollIntervalMs: S.Number },
+      {
+        modelToDependencies: model => ({
+          pollIntervalMs: model.pollIntervalMs,
+        }),
+        dependenciesToStream: ({ pollIntervalMs }) =>
+          Stream.map(Stream.tick(Duration.millis(pollIntervalMs)), () =>
+            PollTicked(),
+          ),
+      },
+    ),
+    hostScope: Port.subscription(ports.inbound.scopeChanged, scopeId =>
+      ScopeChanged({ scopeId }),
+    ),
+  }),
+)
+
+const field = (h: HtmlBuilder<Message>, label: string, value: string): Html =>
+  h.div(
+    [h.Class('pulse__field')],
+    [
+      h.span([h.Class('pulse__label')], [label]),
+      h.span([h.Class('pulse__value')], [value]),
+    ],
+  )
+
+const heartbeatFields = (
+  h: HtmlBuilder<Message>,
+  heartbeat: Heartbeat,
+): ReadonlyArray<Html> => [
+  field(h, 'sequence', String(heartbeat.sequence)),
+  field(h, 'scope echoed back', heartbeat.scopeId),
+  field(h, 'observed at', heartbeat.observedAt),
+]
+
+const body = (h: HtmlBuilder<Message>, model: Model): ReadonlyArray<Html> => {
+  const remote = model.heartbeat
+  switch (remote._tag) {
+    case 'Loading':
+      return [h.p([h.Class('microdot-note')], ['Loading first heartbeat…'])]
+    case 'Ready':
+      return [
+        h.p(
+          [h.Class('microdot-state')],
+          [remote.stale ? 'Refreshing' : 'Ready'],
+        ),
+        ...heartbeatFields(h, remote.value),
+      ]
+    case 'Failed':
+      return [
+        h.p([h.Class('microdot-state microdot-state--error')], ['Failed']),
+        h.p([h.Class('microdot-note')], [remote.error]),
+        ...(remote.last === undefined
+          ? [
+              h.p(
+                [h.Class('microdot-note')],
+                ['No previous value to fall back on.'],
+              ),
+            ]
+          : [
+              h.p([h.Class('microdot-note')], ['Showing the last good value.']),
+              ...heartbeatFields(h, remote.last),
+            ]),
+      ]
+    case 'Unauthorized':
+      return [h.p([h.Class('microdot-state')], ['Unauthorized'])]
+  }
+}
+
+const view = (model: Model, h: HtmlBuilder<Message>): Html =>
+  h.article(
+    [h.Class('starter-card pulse')],
+    [
+      h.header(
+        [],
+        [
+          h.p([h.Class('microdot-overline')], ['Independent service · 3202']),
+          h.h2([], ['Pulse readout']),
+          h.p(
+            [h.Class('microdot-note')],
+            [
+              'Receives scope-id live and still polls when no broker is present.',
+            ],
+          ),
+        ],
+      ),
+      h.div([h.Class('starter-card__body')], body(h, model)),
+      h.footer(
+        [],
+        [
+          h.span(
+            [],
+            [`scope-id ${model.scopeId} · successful polls ${model.polls}`],
+          ),
+          h.button(
+            [h.Class('microdot-action'), h.OnClick(RefreshRequested())],
+            ['Refresh'],
+          ),
+        ],
+      ),
+    ],
+  )
+
+export const makePulseProgram = (
+  container: HTMLElement,
+  attributes: Readonly<Record<string, string>>,
+) => {
+  const apiUrl = attributes['api-url'] ?? ''
+  const scopeId = attributes['scope-id'] ?? 'general'
+  return makeElement<Model, Message, PulseClient, never, typeof ports>({
+    Model,
+    container,
+    ports,
+    resources: pulseClientLive(apiUrl),
+    init: () => [
+      {
+        heartbeat: Loading(),
+        scopeId,
+        apiUrl,
+        pollIntervalMs: POLL_INTERVAL_MS,
+        polls: 0,
+      },
+      [FetchHeartbeat({ scopeId })],
+    ],
+    update,
+    view,
+    subscriptions,
+  })
+}

package/templates/base/microdots/pulse/src/client.ts

@@ -0,0 +1,14 @@
+import { Context } from 'effect'
+import type { Layer } from 'effect'
+import type { RpcClient, RpcClientError } from 'effect/unstable/rpc'
+import { makeRpcClientLive } from '@bespokeagentics/microdots-runtime'
+
+import { PulseRpcs } from './contract.ts'
+
+export class PulseClient extends Context.Service<
+  PulseClient,
+  RpcClient.RpcClient<PulseRpcs, RpcClientError.RpcClientError>
+>()('PulseClient') {}
+
+export const pulseClientLive: (baseUrl: string) => Layer.Layer<PulseClient> =
+  makeRpcClientLive(PulseClient, PulseRpcs)

package/templates/base/microdots/pulse/src/contract.ts

@@ -0,0 +1,32 @@
+import { Schema as S } from 'effect'
+import { Rpc, RpcGroup } from 'effect/unstable/rpc'
+
+export const Heartbeat = S.Struct({
+  id: S.String,
+  sequence: S.Number,
+  observedAt: S.String,
+  service: S.String,
+  scopeId: S.String,
+})
+export type Heartbeat = typeof Heartbeat.Type
+
+export const HeartbeatObserved = S.Struct({
+  id: S.String,
+  sequence: S.Number,
+  scopeId: S.String,
+})
+export type HeartbeatObserved = typeof HeartbeatObserved.Type
+
+export class HeartbeatUnavailable extends S.TaggedError<HeartbeatUnavailable>()(
+  'HeartbeatUnavailable',
+  { reason: S.String },
+) {}
+
+export const GetHeartbeat = Rpc.make('GetHeartbeat', {
+  payload: { scopeId: S.String },
+  success: Heartbeat,
+  error: HeartbeatUnavailable,
+})
+
+export const PulseRpcs = RpcGroup.make(GetHeartbeat)
+export type PulseRpcs = RpcGroup.Rpcs<typeof PulseRpcs>

package/templates/base/microdots/pulse/src/element.ts

@@ -0,0 +1,24 @@
+import { type Disposable, defineMicroDot } from '@bespokeagentics/microdots-element'
+import { Runtime } from 'foldkit'
+
+import { makePulseProgram } from './app.ts'
+import styles from './styles.css?inline'
+import { pulseSurface } from './surface.ts'
+
+type Handle = Runtime.EmbedHandle<ReturnType<typeof makePulseProgram>['ports']> &
+  Disposable
+
+defineMicroDot<Handle, typeof pulseSurface>({
+  surface: pulseSurface,
+  styles,
+  embed: (container, attributes) =>
+    Runtime.embed(makePulseProgram(container, attributes)),
+  receive: {
+    'scope-id': (handle, value) => {
+      handle.ports.scopeChanged.send(value)
+    },
+  },
+  publish: {
+    'heartbeat-observed': handle => handle.ports.heartbeatObserved,
+  },
+})

package/templates/base/microdots/pulse/src/entry.ts

@@ -0,0 +1 @@
+import './element.ts'

package/templates/base/microdots/pulse/src/surface.ts

@@ -0,0 +1,30 @@
+import { makeMicroDotSurface } from '@bespokeagentics/microdots-element'
+
+import { HeartbeatObserved } from './contract.ts'
+
+export const pulseSurface = makeMicroDotSurface({
+  tag: 'starter-pulse',
+  attributes: {
+    'api-url': {
+      type: 'string',
+      required: true,
+      ownership: 'environment',
+      description: "Base URL of the pulse readout's own service.",
+    },
+    'scope-id': {
+      type: 'string',
+      live: true,
+      default: 'general',
+      ownership: 'host-input',
+      description: 'Selected scope; a live write refetches immediately.',
+    },
+  },
+  events: {
+    'heartbeat-observed': {
+      payload: HeartbeatObserved,
+      description: 'Emitted after every successful poll.',
+    },
+  },
+})
+
+export const surfaces = [pulseSurface]

package/templates/base/microdots/pulse/src/tokens.css

@@ -0,0 +1,30 @@
+:where([data-microdot]) {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --font-display: Inter, ui-sans-serif, system-ui, sans-serif;
+  --font-mono: 'SFMono-Regular', Consolas, monospace;
+  --fw-medium: 500;
+  --fs-caption: 0.75rem;
+  --fs-body-s: 0.82rem;
+  --fs-body-m: 0.92rem;
+  --fs-button-sm: 0.78rem;
+  --fs-display-m: 1.5rem;
+  --radius-sm: 0.35rem;
+  --radius-md: 0.55rem;
+  --radius-lg: 0.8rem;
+  --radius-full: 9999px;
+  --text-primary: #18202b;
+  --text-secondary: #465466;
+  --text-muted: #69778a;
+  --text-heading: #111827;
+  --text-on-brand: #ffffff;
+  --surface-default: #ffffff;
+  --surface-raised: #f8fafc;
+  --border-default: #d5dce6;
+  --border-subtle: #e7ebf0;
+  --accent-fill: #5264c7;
+  --accent-fill-hover: #4355b9;
+  --int-hover: rgb(82 100 199 / 0.12);
+  --int-active: rgb(82 100 199 / 0.17);
+  --status-error-fg: #a12b2b;
+  --shadow-card: 0 10px 28px rgb(17 24 39 / 0.08);
+}

package/templates/base/microdots/scope-picker/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@starter/scope-picker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "microdot": {
+    "tags": ["starter-scope-picker"],
+    "port": 3201,
+    "bundle": "scope-picker.js"
+  },
+  "exports": { "./contract": "./src/contract.ts" },
+  "dependencies": {
+    "@bespokeagentics/microdots-element": "0.1.1",
+    "@bespokeagentics/microdots-runtime": "0.1.1",
+    "@bespokeagentics/microdots-theme": "0.1.1",
+    "@effect/platform-node": "4.0.0-rc.108",
+    "effect": "4.0.0-rc.108",
+    "foldkit": "^0.144.0"
+  }
+}

package/templates/base/microdots/scope-picker/service/handlers.ts

@@ -0,0 +1,15 @@
+import { Effect } from 'effect'
+
+import { ScopePickerRpcs } from '../src/contract.ts'
+
+export const ScopePickerHandlersLive = ScopePickerRpcs.toLayer({
+  ListScopes: () =>
+    Effect.succeed({
+      items: [
+        { id: 'general', label: 'General' },
+        { id: 'operations', label: 'Operations' },
+        { id: 'delivery', label: 'Delivery' },
+      ],
+      observedAt: new Date().toISOString(),
+    }),
+})

package/templates/base/microdots/scope-picker/service/main.ts

@@ -0,0 +1,30 @@
+import { Layer } from 'effect'
+import { RpcSerialization, RpcServer } from 'effect/unstable/rpc'
+import {
+  makeRpcService,
+  runRpcService,
+} from '@bespokeagentics/microdots-runtime/service'
+
+import { ScopePickerRpcs } from '../src/contract.ts'
+import { ScopePickerHandlersLive } from './handlers.ts'
+
+const rpcLayer = RpcServer.layerHttp({
+  group: ScopePickerRpcs,
+  path: '/rpc',
+  // Omitting this silently selects WebSocket while the browser POSTs HTTP.
+  protocol: 'http',
+}).pipe(
+  Layer.provide(ScopePickerHandlersLive),
+  Layer.provide(RpcSerialization.layerNdjson),
+)
+
+runRpcService(
+  makeRpcService({
+    rpcLayer,
+    port: 3201,
+    allowedOrigins: [
+      'http://localhost:5190',
+      'http://127.0.0.1:5190',
+    ],
+  }),
+)