@bespokeagentics/create-microdots-host 0.1.0

package/templates/base/microdots/scope-picker/src/app.ts

@@ -0,0 +1,256 @@
+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 { ScopePickerClient, scopePickerClientLive } from './client.ts'
+import { ScopeList, ScopeOption, ScopeSelected } from './contract.ts'
+
+export const POLL_INTERVAL_MS = 10_000
+
+const Loading = ts('Loading')
+const Ready = ts('Ready', { value: ScopeList, stale: S.Boolean })
+const Failed = ts('Failed', { error: S.String, last: S.UndefinedOr(ScopeList) })
+const Unauthorized = ts('Unauthorized')
+const RemoteScopes = S.Union([Loading, Ready, Failed, Unauthorized])
+type RemoteScopes = typeof RemoteScopes.Type
+
+const Model = S.Struct({
+  scopes: RemoteScopes,
+  selectedId: S.String,
+  apiUrl: S.String,
+  pollIntervalMs: S.Number,
+  polls: S.Number,
+})
+type Model = typeof Model.Type
+
+const PollTicked = m('PollTicked')
+const ScopesReceived = m('ScopesReceived', { scopes: ScopeList })
+const ScopesFailed = m('ScopesFailed', { error: S.String })
+const ScopeChosen = m('ScopeChosen', { scope: ScopeOption })
+const ScopePublished = m('ScopePublished')
+const RefreshRequested = m('RefreshRequested')
+const Message = S.Union([
+  PollTicked,
+  ScopesReceived,
+  ScopesFailed,
+  ScopeChosen,
+  ScopePublished,
+  RefreshRequested,
+])
+type Message = typeof Message.Type
+
+export const ports = {
+  inbound: {},
+  outbound: { scopeSelected: Port.outbound(ScopeSelected) },
+}
+
+const FetchScopes = Command.define('FetchScopes', {
+  args: {},
+  messages: [ScopesReceived, ScopesFailed],
+  execute: () =>
+    Effect.gen(function* () {
+      const client = yield* ScopePickerClient
+      const scopes = yield* client.ListScopes()
+      return ScopesReceived({ scopes })
+    }).pipe(
+      Effect.catch(error =>
+        Effect.succeed(
+          ScopesFailed({
+            error:
+              error._tag === 'ScopesUnavailable'
+                ? error.reason
+                : `could not reach the service (${error._tag})`,
+          }),
+        ),
+      ),
+    ),
+})
+
+const PublishScope = Command.define('PublishScope', {
+  args: { scope: ScopeOption },
+  messages: [ScopePublished],
+  execute: ({ scope }) =>
+    Port.emit(ports.outbound.scopeSelected, scope).pipe(
+      Effect.as(ScopePublished()),
+    ),
+})
+
+const refreshing = (remote: RemoteScopes): RemoteScopes =>
+  remote._tag === 'Ready' ? Ready({ value: remote.value, stale: true }) : remote
+
+const lastGood = (remote: RemoteScopes): ScopeList | undefined =>
+  remote._tag === 'Ready'
+    ? remote.value
+    : remote._tag === 'Failed'
+      ? remote.last
+      : undefined
+
+type UpdateResult = readonly [
+  Model,
+  ReadonlyArray<Command.Command<Message, never, ScopePickerClient>>,
+]
+
+const update = (model: Model, message: Message): UpdateResult => {
+  switch (message._tag) {
+    case 'PollTicked':
+    case 'RefreshRequested':
+      return [{ ...model, scopes: refreshing(model.scopes) }, [FetchScopes({})]]
+    case 'ScopesReceived':
+      return [
+        {
+          ...model,
+          scopes: Ready({ value: message.scopes, stale: false }),
+          polls: model.polls + 1,
+        },
+        [],
+      ]
+    case 'ScopesFailed':
+      return [
+        {
+          ...model,
+          scopes: Failed({
+            error: message.error,
+            last: lastGood(model.scopes),
+          }),
+        },
+        [],
+      ]
+    case 'ScopeChosen':
+      return [
+        { ...model, selectedId: message.scope.id },
+        [PublishScope({ scope: message.scope })],
+      ]
+    case 'ScopePublished':
+      return [model, []]
+  }
+}
+
+const subscriptions = Subscription.make<Model, Message, ScopePickerClient>()(
+  entry => ({
+    poll: entry(
+      { pollIntervalMs: S.Number },
+      {
+        modelToDependencies: model => ({
+          pollIntervalMs: model.pollIntervalMs,
+        }),
+        dependenciesToStream: ({ pollIntervalMs }) =>
+          Stream.map(Stream.tick(Duration.millis(pollIntervalMs)), () =>
+            PollTicked(),
+          ),
+      },
+    ),
+  }),
+)
+
+const scopeButtons = (
+  h: HtmlBuilder<Message>,
+  model: Model,
+  scopes: ScopeList,
+): ReadonlyArray<Html> =>
+  scopes.items.map(scope =>
+    h.button(
+      [
+        h.Class(
+          scope.id === model.selectedId
+            ? 'scope-picker__choice scope-picker__choice--selected'
+            : 'scope-picker__choice',
+        ),
+        h.OnClick(ScopeChosen({ scope })),
+      ],
+      [scope.label],
+    ),
+  )
+
+const body = (h: HtmlBuilder<Message>, model: Model): ReadonlyArray<Html> => {
+  const remote = model.scopes
+  switch (remote._tag) {
+    case 'Loading':
+      return [h.p([h.Class('microdot-note')], ['Loading scopes…'])]
+    case 'Ready':
+      return [
+        h.p(
+          [h.Class('microdot-state')],
+          [remote.stale ? 'Refreshing' : 'Ready'],
+        ),
+        h.div(
+          [h.Class('scope-picker__choices')],
+          scopeButtons(h, model, 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.div(
+                [h.Class('scope-picker__choices')],
+                scopeButtons(h, model, 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 scope-picker')],
+    [
+      h.header(
+        [],
+        [
+          h.p([h.Class('microdot-overline')], ['Independent service · 3201']),
+          h.h2([], ['Scope picker']),
+          h.p(
+            [h.Class('microdot-note')],
+            [
+              'Emits an event. The host topology—not this dot—decides who receives it.',
+            ],
+          ),
+        ],
+      ),
+      h.div([h.Class('starter-card__body')], body(h, model)),
+      h.footer(
+        [],
+        [
+          h.span([], [`successful polls ${model.polls}`]),
+          h.button(
+            [h.Class('microdot-action'), h.OnClick(RefreshRequested())],
+            ['Refresh'],
+          ),
+        ],
+      ),
+    ],
+  )
+
+export const makeScopePickerProgram = (
+  container: HTMLElement,
+  attributes: Readonly<Record<string, string>>,
+) => {
+  const apiUrl = attributes['api-url'] ?? ''
+  return makeElement<Model, Message, ScopePickerClient, never, typeof ports>({
+    Model,
+    container,
+    ports,
+    resources: scopePickerClientLive(apiUrl),
+    init: () => [
+      {
+        scopes: Loading(),
+        selectedId: 'general',
+        apiUrl,
+        pollIntervalMs: POLL_INTERVAL_MS,
+        polls: 0,
+      },
+      [FetchScopes({})],
+    ],
+    update,
+    view,
+    subscriptions,
+  })
+}

package/templates/base/microdots/scope-picker/src/client.ts

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

package/templates/base/microdots/scope-picker/src/contract.ts

@@ -0,0 +1,27 @@
+import { Schema as S } from 'effect'
+import { Rpc, RpcGroup } from 'effect/unstable/rpc'
+
+export const ScopeOption = S.Struct({ id: S.String, label: S.String })
+export type ScopeOption = typeof ScopeOption.Type
+
+export const ScopeList = S.Struct({
+  items: S.Array(ScopeOption),
+  observedAt: S.String,
+})
+export type ScopeList = typeof ScopeList.Type
+
+export const ScopeSelected = ScopeOption
+export type ScopeSelected = typeof ScopeSelected.Type
+
+export class ScopesUnavailable extends S.TaggedError<ScopesUnavailable>()(
+  'ScopesUnavailable',
+  { reason: S.String },
+) {}
+
+export const ListScopes = Rpc.make('ListScopes', {
+  success: ScopeList,
+  error: ScopesUnavailable,
+})
+
+export const ScopePickerRpcs = RpcGroup.make(ListScopes)
+export type ScopePickerRpcs = RpcGroup.Rpcs<typeof ScopePickerRpcs>

package/templates/base/microdots/scope-picker/src/element.ts

@@ -0,0 +1,21 @@
+import { type Disposable, defineMicroDot } from '@bespokeagentics/microdots-element'
+import { Runtime } from 'foldkit'
+
+import { makeScopePickerProgram } from './app.ts'
+import styles from './styles.css?inline'
+import { scopePickerSurface } from './surface.ts'
+
+type Handle = Runtime.EmbedHandle<
+  ReturnType<typeof makeScopePickerProgram>['ports']
+> & Disposable
+
+defineMicroDot<Handle, typeof scopePickerSurface>({
+  surface: scopePickerSurface,
+  styles,
+  embed: (container, attributes) =>
+    Runtime.embed(makeScopePickerProgram(container, attributes)),
+  receive: {},
+  publish: {
+    'scope-selected': handle => handle.ports.scopeSelected,
+  },
+})

package/templates/base/microdots/scope-picker/src/entry.ts

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

package/templates/base/microdots/scope-picker/src/surface.ts

@@ -0,0 +1,23 @@
+import { makeMicroDotSurface } from '@bespokeagentics/microdots-element'
+
+import { ScopeSelected } from './contract.ts'
+
+export const scopePickerSurface = makeMicroDotSurface({
+  tag: 'starter-scope-picker',
+  attributes: {
+    'api-url': {
+      type: 'string',
+      required: true,
+      ownership: 'environment',
+      description: "Base URL of the scope picker's own service.",
+    },
+  },
+  events: {
+    'scope-selected': {
+      payload: ScopeSelected,
+      description: "The scope the host should broker to interested MicroDots.",
+    },
+  },
+})
+
+export const surfaces = [scopePickerSurface]

package/templates/base/microdots/scope-picker/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/scripts/build-output.test.ts

@@ -0,0 +1,71 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+import { afterEach, describe, expect, test } from 'vitest'
+
+import type { MicroDotPackage } from './discover.ts'
+import { cleanGeneratedBuildOutputs } from './build-output.ts'
+
+const roots: string[] = []
+
+const makeRoot = (): string => {
+  const root = mkdtempSync(resolve(tmpdir(), 'microdots-build-output-'))
+  roots.push(root)
+  return root
+}
+
+const dotAt = (root: string, name: string): MicroDotPackage => ({
+  name,
+  directory: resolve(root, 'microdots', name),
+  tags: [`${name}-view`],
+  port: 3991,
+  bundle: `${name}.js`,
+})
+
+afterEach(() => {
+  roots.splice(0).forEach(root => {
+    rmSync(root, { recursive: true, force: true })
+  })
+})
+
+describe('aggregate build output cleanup', () => {
+  test('removes stale shared bundles and discovered-dot artifacts', () => {
+    const root = makeRoot()
+    const dot = dotAt(root, 'renamed')
+    const bundleRoot = resolve(root, 'host/public/microdots')
+    const dotDist = resolve(dot.directory, 'dist')
+    mkdirSync(bundleRoot, { recursive: true })
+    mkdirSync(dotDist, { recursive: true })
+    writeFileSync(resolve(bundleRoot, 'old-name.js'), 'stale')
+    writeFileSync(resolve(dotDist, 'old-name.manifest.json'), 'stale')
+
+    cleanGeneratedBuildOutputs(root, [dot])
+
+    expect(readdirSync(bundleRoot)).toEqual([])
+    expect(existsSync(dotDist)).toBe(false)
+  })
+
+  test('refuses a dot outside the exact repository microdots directory', () => {
+    const root = makeRoot()
+    const outside = resolve(root, 'outside')
+    const dist = resolve(outside, 'dist')
+    mkdirSync(dist, { recursive: true })
+    writeFileSync(resolve(dist, 'keep.txt'), 'mine')
+    const dot: MicroDotPackage = {
+      ...dotAt(root, 'escaped'),
+      directory: outside,
+    }
+
+    expect(() => cleanGeneratedBuildOutputs(root, [dot])).toThrow(
+      'refusing to clean dist outside',
+    )
+    expect(existsSync(resolve(dist, 'keep.txt'))).toBe(true)
+  })
+})

package/templates/base/scripts/build-output.ts

@@ -0,0 +1,28 @@
+import { mkdirSync, rmSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+import type { MicroDotPackage } from './discover.ts'
+
+export const cleanGeneratedBuildOutputs = (
+  root: string,
+  dots: ReadonlyArray<MicroDotPackage>,
+): void => {
+  const repositoryRoot = resolve(root)
+  const microdotsRoot = resolve(repositoryRoot, 'microdots')
+  const bundleRoot = resolve(repositoryRoot, 'host/public/microdots')
+
+  for (const dot of dots) {
+    const directory = resolve(dot.directory)
+    if (dirname(directory) !== microdotsRoot) {
+      throw new Error(
+        `[build:${dot.name}] refusing to clean dist outside ${microdotsRoot}: ${directory}`,
+      )
+    }
+  }
+
+  rmSync(bundleRoot, { recursive: true, force: true })
+  mkdirSync(bundleRoot, { recursive: true })
+  dots.forEach(dot => {
+    rmSync(resolve(dot.directory, 'dist'), { recursive: true, force: true })
+  })
+}

package/templates/base/scripts/build.ts

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { cleanGeneratedBuildOutputs } from './build-output.ts'
+import { listMicroDots, repoRoot } from './discover.ts'
+
+const run = (label: string, cwd: string, command: ReadonlyArray<string>): void => {
+  console.log(`[build:${label}] ${command.join(' ')}`)
+  const [executable, ...args] = command
+  if (executable === undefined) throw new Error(`${label} has no build command`)
+  const result = spawnSync(executable, args, {
+    cwd,
+    stdio: 'inherit',
+  })
+  if (result.status !== 0) {
+    throw new Error(`${label} build failed with exit ${String(result.status)}`)
+  }
+}
+
+const dots = listMicroDots()
+cleanGeneratedBuildOutputs(repoRoot, dots)
+dots.forEach(dot => {
+  run(dot.name, dot.directory, ['bunx', 'vite', 'build'])
+})
+// The Vite plugin is intentionally warn-only so a transient manifest failure
+// cannot kill a long-running watcher. A one-shot release build needs the
+// opposite contract: re-run every emitter strictly and fail the aggregate.
+run('manifests', repoRoot, ['bun', 'scripts/emit-manifests.ts'])
+dots.forEach(dot => {
+  const manifest = resolve(dot.directory, 'dist', `${dot.name}.manifest.json`)
+  if (!existsSync(manifest)) {
+    throw new Error(`[build:${dot.name}] manifest is missing: ${manifest}`)
+  }
+})
+run('host', resolve(repoRoot, 'host'), ['bunx', 'vite', 'build'])
+console.log('[build] complete')

package/templates/base/scripts/check-tokens.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { repoRoot } from './discover.ts'
+
+const withoutComments = (css: string): string =>
+  css.replace(/\/\*[\s\S]*?\*\//g, '')
+
+const cssFiles = (directory: string): ReadonlyArray<string> =>
+  existsSync(directory)
+    ? readdirSync(directory)
+        .filter(name => name !== 'node_modules')
+        .flatMap(name => {
+          const path = resolve(directory, name)
+          return statSync(path).isDirectory()
+            ? cssFiles(path)
+            : path.endsWith('.css')
+              ? [path]
+              : []
+        })
+    : []
+
+const referencesIn = (paths: ReadonlyArray<string>): ReadonlySet<string> =>
+  new Set(
+    paths.flatMap(path =>
+      [...withoutComments(readFileSync(path, 'utf8')).matchAll(/var\((--[\w-]+)/g)].map(
+        match => match[1] ?? '',
+      ),
+    ),
+  )
+
+const declarationsIn = (path: string): ReadonlySet<string> =>
+  new Set(
+    [...withoutComments(readFileSync(path, 'utf8')).matchAll(/(--[\w-]+)\s*:/g)].map(
+      match => match[1] ?? '',
+    ),
+  )
+
+const themePackage = resolve(
+  repoRoot,
+  'node_modules/@bespokeagentics/microdots-theme/src/theme.css',
+)
+const consumers = [
+  ...cssFiles(resolve(repoRoot, 'host/src')),
+  ...cssFiles(resolve(repoRoot, 'microdots')),
+  ...(existsSync(themePackage) ? [themePackage] : []),
+]
+const required = referencesIn(consumers)
+const themes = cssFiles(resolve(repoRoot, 'host/public/themes'))
+
+if (themes.length < 2) {
+  throw new Error('[tokens] expected at least two theme sets')
+}
+
+themes.forEach(path => {
+  const declared = declarationsIn(path)
+  const missing = [...required].filter(name => !declared.has(name)).sort()
+  if (missing.length > 0) {
+    throw new Error(`[tokens] ${path} is missing ${missing.join(', ')}`)
+  }
+})
+
+console.log(`[tokens] ${themes.length} sets satisfy ${required.size} referenced tokens`)

package/templates/base/scripts/dev.ts

@@ -0,0 +1,78 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+
+import { listMicroDots, repoRoot } from './discover.ts'
+
+const children: Array<ReturnType<typeof spawn>> = []
+let stopping = false
+
+const start = (
+  label: string,
+  cwd: string,
+  command: ReadonlyArray<string>,
+): void => {
+  const [executable, ...args] = command
+  if (executable === undefined) throw new Error(`${label} has no command`)
+  const child = spawn(executable, args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  children.push(child)
+  const pipe = (stream: NodeJS.ReadableStream | null): void => {
+    stream?.on('data', chunk => {
+      String(chunk)
+        .split('\n')
+        .filter(line => line.trim() !== '')
+        .forEach(line => console.log(`[${label}] ${line}`))
+    })
+  }
+  pipe(child.stdout)
+  pipe(child.stderr)
+  child.on('exit', code => {
+    if (!stopping) console.log(`[${label}] exited with ${String(code)}`)
+  })
+}
+
+const stop = (): void => {
+  if (stopping) return
+  stopping = true
+  children.forEach(child => child.kill('SIGTERM'))
+}
+
+process.on('SIGINT', stop)
+process.on('SIGTERM', stop)
+
+const dots = listMicroDots()
+
+// A fresh scaffold has no bundles for the host to import. Build once before the
+// concurrent watchers start so the first browser load cannot race them and turn
+// a healthy MicroDot into a sticky load-failure placeholder.
+dots.forEach(dot => {
+  console.log(`[dev] preparing ${dot.name}`)
+  const prepared = spawnSync('bunx', ['vite', 'build'], {
+    cwd: dot.directory,
+    stdio: 'inherit',
+  })
+  if (prepared.status !== 0) {
+    throw new Error(
+      `[dev] ${dot.name} initial build failed with exit ${String(prepared.status)}`,
+    )
+  }
+})
+
+dots.forEach(dot => {
+  start(`${dot.name}:service`, dot.directory, [
+    'bun',
+    '--watch',
+    'service/main.ts',
+  ])
+  start(`${dot.name}:bundle`, dot.directory, [
+    'bunx',
+    'vite',
+    'build',
+    '--watch',
+  ])
+})
+start('host', resolve(repoRoot, 'host'), ['bunx', 'vite', 'dev'])
+
+console.log('[dev] http://localhost:5190 — Ctrl-C stops every owned process')