@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/studio/server/introspect/source-overlay/project.ts

@@ -0,0 +1,248 @@
+/**
+ * Tolerant ts-morph project construction and authored-source resolution.
+ *
+ * This module owns syntax/value lookup only. It does not interpret handlers or
+ * schema members.
+ */
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve as resolvePath } from 'node:path'
+import { Node, Project, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
+
+/** A fresh, in-memory-ish ts-morph project: no tsconfig, tolerant of errors. */
+export function newProject(): Project {
+  return new Project({
+    useInMemoryFileSystem: false,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true,
+    compilerOptions: {
+      allowJs: true,
+      // `allowImportingTsExtensions` keeps `.ts`-suffixed imports from blowing up.
+      allowImportingTsExtensions: true,
+    },
+  })
+}
+
+/** Add a file to the project if it exists; returns undefined otherwise. */
+export function tryAddFile(project: Project, file: string): SourceFile | undefined {
+  try {
+    if (!existsSync(file)) return undefined
+    return project.getSourceFile(file) ?? project.addSourceFileAtPath(file)
+  } catch {
+    return undefined
+  }
+}
+
+/** Path relative to `root`, POSIX-style ('schema/monitor.ts'), never absolute. */
+export function relToRoot(root: string, file: string): string {
+  const abs = isAbsolute(file) ? file : resolvePath(root, file)
+  const canonical = (value: string) => {
+    try {
+      return realpathSync(value)
+    } catch {
+      return value
+    }
+  }
+  return relative(canonical(root), canonical(abs)).split('\\').join('/')
+}
+
+/** The call's callee identifier name, e.g. `method` / `classMethods` / `todo`. */
+export function calleeName(call: CallExpression): string | undefined {
+  const expr = call.getExpression()
+  if (Node.isIdentifier(expr)) return expr.getText()
+  if (Node.isPropertyAccessExpression(expr)) return expr.getName()
+  return undefined
+}
+
+/** Remove syntax-only wrappers around a runtime value. */
+export function unwrapExpression(node: Node): Node {
+  let current = node
+  while (
+    Node.isParenthesizedExpression(current) ||
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isTypeAssertion(current)
+  ) {
+    current = current.getExpression()
+  }
+  return current
+}
+
+/** Resolve a local or relatively imported identifier to its runtime value. */
+export function valueOfIdentifier(id: Node): Node | undefined {
+  if (!Node.isIdentifier(id)) return undefined
+  const decl = firstValueDeclaration(id)
+  if (decl && Node.isVariableDeclaration(decl)) return decl.getInitializer()
+  return resolveImportedValue(id)
+}
+
+/** Follow a named relative import to the exported value that defines it. */
+function resolveImportedValue(id: Node): Node | undefined {
+  if (!Node.isIdentifier(id)) return undefined
+  const localName = id.getText()
+  const sourceFile = id.getSourceFile()
+
+  for (const imp of sourceFile.getImportDeclarations()) {
+    for (const named of imp.getNamedImports()) {
+      const local = named.getAliasNode()?.getText() ?? named.getName()
+      if (local !== localName) continue
+      const target = resolveModuleFile(sourceFile, imp.getModuleSpecifierValue())
+      if (!target) return undefined
+      return findExportedValue(id.getProject(), target, named.getName(), new Set<string>())
+    }
+  }
+  return undefined
+}
+
+/** Find an exported variable/function value, following local and barrel exports. */
+function findExportedValue(
+  project: Project,
+  file: string,
+  exportName: string,
+  seen: Set<string>,
+): Node | undefined {
+  const key = `${file}:${exportName}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  const sf = tryAddFile(project, file)
+  if (!sf) return undefined
+
+  const localValue = (name: string, exportedOnly: boolean): Node | undefined => {
+    const variable = sf
+      .getVariableDeclarations()
+      .find(
+        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
+      )
+    if (variable) return variable.getInitializer()
+    return sf
+      .getFunctions()
+      .find(
+        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
+      )
+  }
+
+  const direct = localValue(exportName, true)
+  if (direct) return direct
+
+  for (const ex of sf.getExportDeclarations()) {
+    const modSpec = ex.getModuleSpecifierValue()
+    const target = modSpec ? resolveModuleFile(sf, modSpec) : undefined
+    const named = ex.getNamedExports()
+    if (named.length > 0) {
+      for (const specifier of named) {
+        const exposed = specifier.getAliasNode()?.getText() ?? specifier.getName()
+        if (exposed !== exportName) continue
+        const original = specifier.getName()
+        if (target) return findExportedValue(project, target, original, seen)
+        return localValue(original, false)
+      }
+    } else if (target) {
+      const found = findExportedValue(project, target, exportName, seen)
+      if (found) return found
+    }
+  }
+  return undefined
+}
+
+/** Get the value node of an object-literal property (handles shorthand). */
+export function getProp(obj: Node, name: string): Node | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop) return undefined
+  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
+  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
+  if (Node.isMethodDeclaration(prop)) return prop
+  return prop
+}
+
+/** First value/declaration node a name resolves to (definition, not reference). */
+export function firstValueDeclaration(node: Node): Node | undefined {
+  const idNode = Node.isIdentifier(node)
+    ? node
+    : node.getFirstDescendantByKind(SyntaxKind.Identifier)
+  if (!idNode || !Node.isIdentifier(idNode)) return undefined
+  const symbol = idNode.getSymbol()
+  if (!symbol) return undefined
+  const decls = symbol.getDeclarations()
+  return decls[0]
+}
+
+/** Resolve a relative module specifier to a concrete .ts file path on disk. */
+export function resolveModuleFile(from: SourceFile, spec: string): string | undefined {
+  if (!spec.startsWith('.')) {
+    // Current SDK projects use package `imports` aliases such as
+    // `#actions/risk`. Resolve them from the authored file's directory through
+    // Bun so the overlay follows the same project-local map as runtime imports.
+    if (!spec.startsWith('#')) return undefined
+    try {
+      const resolved = Bun.resolveSync(spec, dirname(from.getFilePath()))
+      if (existsSync(resolved)) return resolved
+    } catch {
+      return undefined
+    }
+    return undefined
+  }
+  const baseDir = dirname(from.getFilePath())
+  const base = resolvePath(baseDir, spec)
+  const sourceBase = base.replace(/\.(?:[cm]?js|jsx)$/, '')
+  const candidates = [
+    base,
+    sourceBase.endsWith('.ts') ? sourceBase : `${sourceBase}.ts`,
+    sourceBase.endsWith('.tsx') ? sourceBase : `${sourceBase}.tsx`,
+    `${base}/index.ts`,
+    `${base}/index.tsx`,
+  ]
+  for (const c of candidates) if (existsSync(c)) return c
+  return undefined
+}
+
+/** Resolve a value to an object literal, following local/imported identifiers. */
+export function resolveObjectLiteral(
+  node: Node,
+  seen = new Set<string>(),
+): import('ts-morph').ObjectLiteralExpression | undefined {
+  const value = unwrapExpression(node)
+  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  if (Node.isObjectLiteralExpression(value)) return value
+  if (Node.isIdentifier(value)) {
+    const resolved = valueOfIdentifier(value)
+    if (resolved) return resolveObjectLiteral(resolved, seen)
+  }
+  return undefined
+}
+
+/** Value carried by an object-literal property, including shorthand/method syntax. */
+export function objectPropertyValue(prop: Node): Node | undefined {
+  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
+  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
+  if (Node.isMethodDeclaration(prop)) return prop
+  return undefined
+}
+
+/** A string-literal property value, e.g. `as: 'page'` → 'page'. */
+export function stringLiteralOfProp(obj: Node, name: string): string | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop || !Node.isPropertyAssignment(prop)) return undefined
+  const v = prop.getInitializer()
+  if (v && (Node.isStringLiteral(v) || Node.isNoSubstitutionTemplateLiteral(v)))
+    return v.getLiteralText()
+  return undefined
+}
+
+/** The key name of an object-literal property (assignment / shorthand / method). */
+export function propertyKey(prop: Node): string | undefined {
+  if (
+    Node.isPropertyAssignment(prop) ||
+    Node.isShorthandPropertyAssignment(prop) ||
+    Node.isMethodDeclaration(prop)
+  ) {
+    const nameNode = prop.getNameNode()
+    if (Node.isStringLiteral(nameNode)) return nameNode.getLiteralText()
+    if (Node.isComputedPropertyName(nameNode)) return undefined // skip `[expr]: …`
+    return nameNode.getText()
+  }
+  // Spread (`...knobs`) — no single key.
+  return undefined
+}

package/studio/server/introspect/source-overlay/spans.ts

@@ -0,0 +1,330 @@
+/**
+ * Source coordinates and leading documentation for authored schema members.
+ */
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { Node, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
+
+import type { SchemaIR, SourceSpan } from '../../../shared/types'
+
+import {
+  calleeName,
+  newProject,
+  objectPropertyValue,
+  propertyKey,
+  relToRoot,
+  resolveObjectLiteral,
+  stringLiteralOfProp,
+  unwrapExpression,
+  valueOfIdentifier,
+} from './project'
+
+/**
+ * Harvest the leading JSDoc / line-comment block immediately above `node`,
+ * stripped of comment markers, collapsed to a single trimmed string.
+ */
+function leadingDoc(node: Node): string | undefined {
+  // Prefer real JSDoc nodes when present (ts-morph exposes them on many decls).
+  const anyNode = node as unknown as { getJsDocs?: () => Array<{ getText: () => string }> }
+  if (typeof anyNode.getJsDocs === 'function') {
+    const docs = anyNode.getJsDocs()
+    if (docs.length > 0) {
+      const text = docs.map((d) => d.getText()).join('\n')
+      const cleaned = cleanComment(text)
+      if (cleaned) return cleaned
+    }
+  }
+  // Fall back to raw leading comment ranges (covers `//` line comments too).
+  const ranges = node.getLeadingCommentRanges()
+  if (ranges.length === 0) return undefined
+  const raw = ranges.map((r) => r.getText()).join('\n')
+  const cleaned = cleanComment(raw)
+  return cleaned || undefined
+}
+
+/** Strip `/** *​/`, `//`, leading `*` gutters; collapse to a tidy single line. */
+function cleanComment(raw: string): string {
+  const lines = raw
+    .replace(/\/\*\*?/g, '')
+    .replace(/\*\//g, '')
+    .split('\n')
+    .map((l) =>
+      l
+        .replace(/^\s*\*\s?/, '')
+        .replace(/^\s*\/\/\s?/, '')
+        .trim(),
+    )
+    .filter((l) => l.length > 0)
+  return lines.join(' ').replace(/\s+/g, ' ').trim()
+}
+
+const DECL_HELPERS: Record<string, 'node' | 'edge' | 'function'> = {
+  nodeClass: 'node',
+  edgeClass: 'edge',
+  fn: 'function',
+}
+
+/** Recognize current Class and Function declaration helpers. */
+function declarationHelper(call: CallExpression): 'node' | 'edge' | 'function' | undefined {
+  const direct = calleeName(call)
+  if (direct && direct in DECL_HELPERS) return DECL_HELPERS[direct]
+  const expression = call.getExpression()
+  if (
+    Node.isPropertyAccessExpression(expression) &&
+    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
+    expression.getExpression().getText() === 'edgeClass'
+  ) {
+    return 'edge'
+  }
+  return undefined
+}
+
+/**
+ * A schema member's true NAME + section, resolved from the `defineSchema` map.
+ * Declaration helpers carry no name: the `defineSchema` key is authoritative.
+ */
+interface MemberName {
+  schemaName: string
+  section: 'class' | 'function'
+}
+
+interface MemberNameMap {
+  /** Exact declaration initializer, robust to imported/local aliases. */
+  byValue: Map<string, MemberName>
+  /** Fallback when a symbol cannot be resolved. */
+  byIdentifier: Map<string, MemberName>
+}
+
+/** Stable source coordinate for the value behind a local/imported alias. */
+function memberValueKey(node: Node, seen = new Set<string>()): string | undefined {
+  const value = unwrapExpression(node)
+  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  if (Node.isIdentifier(value)) {
+    const resolved = valueOfIdentifier(value)
+    if (resolved) return memberValueKey(resolved, seen)
+  }
+  return key
+}
+
+/** Map each registered member VARIABLE (as referenced in `defineSchema`) to its
+ *  schema name + section, from the domain's own schema files — never node_modules
+ *  (a dependency's `defineSchema` is not this domain's). */
+function buildMemberNameMap(files: SourceFile[]): MemberNameMap {
+  const map: MemberNameMap = {
+    byValue: new Map<string, MemberName>(),
+    byIdentifier: new Map<string, MemberName>(),
+  }
+  for (const sf of files) {
+    if (sf.getFilePath().includes('/node_modules/')) continue
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (calleeName(call) !== 'defineSchema') continue
+      const input = call.getArguments()[1]
+      const cfg = input ? resolveObjectLiteral(input) : undefined
+      if (!cfg) continue
+      collectSchemaSection(map, cfg, 'classes', 'class')
+      collectSchemaSection(map, cfg, 'functions', 'function')
+    }
+  }
+  return map
+}
+
+/** Record `variable → { schemaName, section }` for one `defineSchema` section,
+ *  handling both `Key: alias` and shorthand `Key`. */
+function collectSchemaSection(
+  map: MemberNameMap,
+  cfg: Node,
+  prop: 'classes' | 'functions',
+  section: 'class' | 'function',
+): void {
+  const obj = getObjectProp(cfg, prop)
+  if (!obj) return
+  for (const p of obj.getProperties()) {
+    const schemaName = propertyKey(p)
+    const memberValue = objectPropertyValue(p)
+    if (!schemaName || !memberValue) continue
+    const member = { schemaName, section } satisfies MemberName
+    const valueKey = memberValueKey(memberValue)
+    if (valueKey) map.byValue.set(valueKey, member)
+    const unwrapped = unwrapExpression(memberValue)
+    if (Node.isIdentifier(unwrapped)) map.byIdentifier.set(unwrapped.getText(), member)
+  }
+}
+
+/**
+ * The anchor namespace for a declared member. The Class section plus helper/IR
+ * kind distinguishes Node and Edge Classes.
+ */
+function resolveMemberKind(
+  ir: SchemaIR | null,
+  name: string,
+  section: 'class' | 'function' | undefined,
+  helperKind: 'node' | 'edge' | 'function',
+): 'class' | 'edge' | 'function' {
+  if (section === 'function' || helperKind === 'function') return 'function'
+  const isEdge = helperKind === 'edge' || ir?.classes?.[name]?.type === 'edge'
+  if (section === 'class') return isEdge ? 'edge' : 'class'
+  return isEdge ? 'edge' : 'class'
+}
+
+export function buildSourceSpans(args: {
+  ir: SchemaIR | null
+  schemaDir: string
+}): Record<string, SourceSpan> {
+  const { ir, schemaDir } = args
+  if (!schemaDir || !existsSync(schemaDir)) return {}
+
+  // The domain root is the parent of the schema dir (spans are relative to it).
+  const domainRoot = dirname(schemaDir.replace(/\/$/, ''))
+
+  const project = newProject()
+  let files: string[] = []
+  try {
+    const added = project.addSourceFilesAtPaths(`${schemaDir.replace(/\/$/, '')}/**/*.ts`)
+    files = added.map((f) => f.getFilePath())
+  } catch {
+    return {}
+  }
+
+  const spans: Record<string, SourceSpan> = {}
+
+  const sourceFiles = files.map((f) => project.getSourceFile(f)).filter((f): f is SourceFile => !!f)
+  // The Domain's `defineSchema` map is authoritative for each member's name.
+  const memberNames = buildMemberNameMap(sourceFiles)
+
+  for (const sf of sourceFiles) {
+    const fileRel = relToRoot(domainRoot, sf.getFilePath())
+
+    for (const v of sf.getVariableDeclarations()) {
+      if (!v.isExported()) continue
+      const init = v.getInitializer()
+      if (!init || !Node.isCallExpression(init)) continue
+      const helperKind = declarationHelper(init)
+      if (!helperKind) continue
+      const valueKey = memberValueKey(init)
+      const member =
+        (valueKey ? memberNames.byValue.get(valueKey) : undefined) ??
+        memberNames.byIdentifier.get(v.getName())
+      const name = member?.schemaName ?? v.getName()
+      const ns = resolveMemberKind(ir, name, member?.section, helperKind)
+
+      const stmt = v.getVariableStatement() ?? v
+      spans[`${ns}.${name}`] = makeSpan(domainRoot, fileRel, stmt, v)
+
+      // The single object-literal argument: nodeClass({ properties, methods })
+      // and current edgeClass.directed({ source, target, properties }).
+      const cfgArg = init.getArguments()[0]
+      if (ns !== 'function' && cfgArg && Node.isObjectLiteralExpression(cfgArg)) {
+        collectPropsAndMethods(spans, ns, name, cfgArg, domainRoot, fileRel)
+      }
+
+      // Edges: endpoints are the first two args; props live in the third.
+      if (ns === 'edge') {
+        collectEdge(spans, name, init, domainRoot, fileRel)
+      }
+    }
+  }
+
+  return spans
+}
+
+/** Build a SourceSpan, harvesting leading doc from the declaration `docNode`. */
+function makeSpan(domainRoot: string, fileRel: string, spanNode: Node, docNode: Node): SourceSpan {
+  const span: SourceSpan = {
+    file: fileRel,
+    startLine: spanNode.getStartLineNumber(),
+    endLine: spanNode.getEndLineNumber(),
+  }
+  const doc = leadingDoc(docNode) ?? leadingDoc(spanNode)
+  if (doc) span.doc = doc
+  return span
+}
+
+/** Record `<ns>.<Name>.property.<p>` and `.method.<m>` from a config object. */
+function collectPropsAndMethods(
+  spans: Record<string, SourceSpan>,
+  ns: string,
+  name: string,
+  cfg: Node,
+  domainRoot: string,
+  fileRel: string,
+): void {
+  if (!Node.isObjectLiteralExpression(cfg)) return
+  const propsObj = getObjectProp(cfg, 'properties') ?? getObjectProp(cfg, 'props')
+  if (propsObj) {
+    for (const p of propsObj.getProperties()) {
+      const pName = propertyKey(p)
+      if (!pName) continue
+      spans[`${ns}.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
+    }
+  }
+  const methodsObj = getObjectProp(cfg, 'methods')
+  if (methodsObj) {
+    for (const m of methodsObj.getProperties()) {
+      const mName = propertyKey(m)
+      if (!mName) continue
+      spans[`${ns}.${name}.method.${mName}`] = makeSpan(domainRoot, fileRel, m, m)
+    }
+  }
+}
+
+/** Record edge endpoint and property spans from current directed/undirected forms. */
+function collectEdge(
+  spans: Record<string, SourceSpan>,
+  name: string,
+  init: CallExpression,
+  domainRoot: string,
+  fileRel: string,
+): void {
+  const argsList = init.getArguments()
+  const expression = init.getExpression()
+  const currentObjectForm =
+    Node.isPropertyAccessExpression(expression) &&
+    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
+    argsList[0] &&
+    Node.isObjectLiteralExpression(argsList[0])
+
+  if (currentObjectForm) {
+    const config = argsList[0]
+    if (Node.isObjectLiteralExpression(config)) {
+      for (const endpointName of ['source', 'target'] as const) {
+        const ep = getObjectProp(config, endpointName)
+        if (!ep) continue
+        const role = stringLiteralOfProp(ep, 'as') ?? stringLiteralOfProp(ep, 'role')
+        if (role) spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
+      }
+      const properties = getObjectProp(config, 'properties') ?? getObjectProp(config, 'props')
+      if (properties) {
+        for (const p of properties.getProperties()) {
+          const pName = propertyKey(p)
+          if (!pName) continue
+          spans[`edge.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
+        }
+      }
+    }
+    return
+  }
+
+  for (let i = 0; i < Math.min(2, argsList.length); i++) {
+    const ep = argsList[i]
+    if (!Node.isObjectLiteralExpression(ep)) continue
+    const role = stringLiteralOfProp(ep, 'as')
+    if (!role) continue
+    spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
+  }
+}
+
+/** The object-literal value of a named property, if it is itself an object. */
+function getObjectProp(
+  obj: Node,
+  name: string,
+): import('ts-morph').ObjectLiteralExpression | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop) return undefined
+  let value: Node | undefined
+  if (Node.isPropertyAssignment(prop)) value = prop.getInitializer()
+  else if (Node.isShorthandPropertyAssignment(prop)) value = prop.getNameNode()
+  return value ? resolveObjectLiteral(value) : undefined
+}

package/studio/server/json.ts

@@ -0,0 +1,46 @@
+/** Pure structural helpers for JSON trust boundaries. */
+
+export type JsonRecord = Record<string, unknown>
+export type JsonDecoder<T> = (value: unknown) => T | undefined
+
+export function asJsonRecord(value: unknown): JsonRecord | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as JsonRecord)
+    : undefined
+}
+
+export function asJsonArray(value: unknown): unknown[] | undefined {
+  return Array.isArray(value) ? value : undefined
+}
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
+export function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined
+}
+
+export function asFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+export function asStringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined
+}
+
+export function asStringRecord(value: unknown): Record<string, string> | undefined {
+  const record = asJsonRecord(value)
+  if (!record || Object.values(record).some((item) => typeof item !== 'string')) return undefined
+  return record as Record<string, string>
+}
+
+/** Parse JSON as untrusted data. `undefined` means syntax failure. */
+export function parseJson(text: string): unknown | undefined {
+  try {
+    const value: unknown = JSON.parse(text)
+    return value
+  } catch {
+    return undefined
+  }
+}

package/studio/server/lifecycle.ts

@@ -26,7 +26,11 @@ export async function bootDomain(handle: DomainHandle): Promise<BootedDomain> {
   if (!loadBaseline(handle.root))
     captureBaseline(
       handle.root,
-      bundle?.ir ?? null,
+      {
+        ir: bundle?.ir ?? null,
+        root: bundle?.schemaMode === 'canonical-admitted' ? (bundle.schemaRoot ?? null) : null,
+        revision: bundle?.schemaRevision ?? null,
+      },
       hashAnatomyFiles(handle.root, handle.schemaDirName),
     )
   const stop = watchDomain(handle)

package/studio/server/sse.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from 'bun:test'
+
+import { broadcast, sseResponse } from './sse'
+
+test('SSE response preserves headers and emits the initial workspace frame', async () => {
+  const response = sseResponse(['issues', 'shell'])
+  expect(response.status).toBe(200)
+  expect(response.headers.get('content-type')).toBe('text/event-stream')
+  expect(response.headers.get('cache-control')).toBe('no-cache, no-transform')
+  expect(response.headers.get('connection')).toBe('keep-alive')
+
+  const reader = response.body!.getReader()
+  const first = await reader.read()
+  expect(new TextDecoder().decode(first.value)).toBe(
+    'data: {"type":"hello","domains":["issues","shell"]}\n\n',
+  )
+
+  expect(broadcast({ type: 'workspace', domains: ['issues', 'billing'] })).toBe(1)
+  const update = await reader.read()
+  expect(new TextDecoder().decode(update.value)).toBe(
+    'data: {"type":"workspace","domains":["issues","billing"]}\n\n',
+  )
+
+  await reader.cancel()
+  expect(broadcast({ type: 'workspace', domains: [] })).toBe(0)
+})

package/studio/server/sse.ts

@@ -41,7 +41,9 @@ export function sseResponse(domains: string[]): Response {
   })
 }
 
-export function broadcast(event: StudioEvent): void {
+/** Broadcast an event and report how many clients were registered at dispatch start. */
+export function broadcast(event: StudioEvent): number {
+  const recipients = clients.size
   const payload = encoder.encode(frame(event))
   for (const [id, c] of clients) {
     try {
@@ -50,6 +52,7 @@ export function broadcast(event: StudioEvent): void {
       clients.delete(id)
     }
   }
+  return recipients
 }
 
 function frame(event: StudioEvent): string {