@lincyaw/server 1.0.0-rc.0 → 1.0.0-rc.1

package/src/server.ts

@@ -1,86 +1,70 @@
-import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
 import { chmodSync, mkdirSync, writeFileSync } from 'node:fs'
 import type { IncomingMessage } from 'node:http'
 import { dirname } from 'node:path'
-import { APPROVALS, eventStream, isRecord, MAX_BODY, MCP_ENDPOINT, errorMessage, prefixed } from '@lincyaw/kernel'
-import type {
-  ApprovalKind,
-  Logger,
-  McpEndpoint,
-  Member,
-  ProxySpec,
-  Route,
-  ServerContext,
-  ServerContribution,
-  ServiceToken,
-} from '@lincyaw/kernel'
+import { APPROVALS, errorMessage, hasRole, MAX_BODY, MCP_ENDPOINT, problemResponse } from '@lincyaw/kernel'
+import type { ApprovalKind, Logger, Member, ProxySpec, Route, ServiceToken } from '@lincyaw/kernel'
 import { pluginLogger } from '@lincyaw/compiler'
 import { createPresmiumMcp } from '@lincyaw/mcp'
 import type { McpCaller } from '@lincyaw/mcp'
-import { authenticate, LOCAL_AUTHOR, machineHosts } from './auth.ts'
+import { authenticate, machineHosts } from './auth.ts'
+import type { MachineHosts } from './auth.ts'
 import type { Refusal } from './auth.ts'
-import { Control, hasRole } from './control.ts'
-import type { ApprovalPolicy, WindowPosition } from './control.ts'
-import { focusBody, FocusStore } from './focus.ts'
-import type { ServedDocument, ServerHost } from './host.ts'
-import { bearer, closeServer, createProxy, header, isLoopback, json, limitBody, listen, nodeServer, problem, urlHost } from './http.ts'
+import { ControlChannel } from './control.ts'
+import type { ApprovalPolicy } from './control.ts'
+import { FocusStore } from './focus.ts'
+import { DiagnosticStore } from './diagnostics.ts'
+import { bearer, createProxy, header, isLoopback, limitBody, listen, nodeServer, normalizeHostName, urlHost } from './http.ts'
 import type { Decision, ProxyTarget } from './http.ts'
-import { serverMcpHost } from './mcp.ts'
-
-export { LOCAL_AUTHOR }
-
-export const SERVER_PATH = '/__presmium/presmium.server'
+import { McpTokens } from './mcp-access.ts'
+import { serverMcpHost } from './mcp-host.ts'
+import { Mounts } from './mounts.ts'
+import { createServerRouteHandler, SERVER_PATH } from './server-routes.ts'
+import type { ServedDocument, ServerHost } from './server-host.ts'
 
 function isMcp(path: string): boolean {
   return path === '/mcp' || path.startsWith('/mcp/')
 }
 
-function endedBy(response: Response, signal: AbortSignal, done: () => void): Response {
-  if (!response.body) {
-    done()
-    return response
-  }
-  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>()
-  void response.body.pipeTo(writable, { signal, preventAbort: true })
-    .catch(() => writable.close().catch(() => undefined))
-    .finally(done)
-  return new Response(readable, { status: response.status, statusText: response.statusText, headers: response.headers })
-}
-
 export interface ServerOptions {
   mode: 'dev' | 'serve'
-  host?: string
+  listenAddress?: string
   port?: number
   document(dir: string): Promise<ServedDocument | undefined>
   serverHost?: ServerHost
   settings?: Record<string, Record<string, unknown>>
   approvals?: Partial<Record<ApprovalKind, ApprovalPolicy>>
-  forward?(): string | undefined
+  /** The origin to forward a path of the site to (in `serve`): the dev server that serves it. */
+  forward?(path: string): string | undefined | Promise<string | undefined>
   operatorDir?: string
+  /**
+   * The address browsers use when a reverse proxy fronts the server: its host is trusted as this machine's, and pages
+   * are advertised under it. A path (`https://host/user/a/preview/`) is the base below which the proxy forwards the
+   * unchanged path; the server's own routes are found below it, and still at the root for calls on its own address.
+   */
+  publicUrl?: string
   stateFile?: string
   mcp?(request: Request, access: McpCaller): Promise<Response>
   env?: NodeJS.ProcessEnv
   approvalTimeoutMs?: number
   log?: Logger
+  diagnostics?: DiagnosticStore
 }
 
 export interface PresmiumServer {
   url: string
+  /** The address browsers use: `publicUrl` when given, else `url`. */
+  publicUrl: string
   port: number
-  token: string
+  mcpToken: string
   services: [ServiceToken<unknown>, unknown][]
-  control: Control
+  control: ControlChannel
+  diagnostics: DiagnosticStore
   serverHost?: ServerHost
-  unmount(dir: string): Promise<void>
+  unmount(dir: string, options?: { preserveFocus?: boolean }): Promise<void>
   close(): Promise<void>
 }
 
-interface Mounted {
-  doc: ServedDocument
-  contributions: Map<string, ServerContribution>
-}
-
-function pluginPath(pathname: string): { plugin: string, path: string, raw: string, plain: boolean } | undefined {
+function parsePluginPath(pathname: string): { plugin: string, path: string, raw: string, plain: boolean } | undefined {
   const match = /^\/__presmium\/([^/]+)\/?(.*)$/.exec(pathname)
   if (!match) return undefined
   const raw = match[2]!
@@ -116,7 +100,7 @@ function findProxy(proxies: ProxySpec[] | undefined, path: string): { spec: Prox
   return undefined
 }
 
-function documentOf(headers: IncomingMessage['headers'], url: URL): string {
+function requestedDocument(headers: IncomingMessage['headers'], url: URL): string {
   const value = header(headers, 'presmium-document') ?? url.searchParams.get('document') ?? ''
   try {
     return decodeURIComponent(value).replace(/^\/+|\/+$/g, '')
@@ -125,105 +109,49 @@ function documentOf(headers: IncomingMessage['headers'], url: URL): string {
   }
 }
 
-function remoteHost(mode: ServerOptions['mode'], host: string, port: number | undefined): string | undefined {
-  if (mode === 'serve' || isLoopback(host)) return undefined
+function remoteListenRefusal(mode: ServerOptions['mode'], listenAddress: string, port: number | undefined): string | undefined {
+  if (mode === 'serve' || isLoopback(listenAddress)) return undefined
   const at = port || 'its port'
-  return `presmium ${mode} listens on this machine only, not on ${host}: it serves the one user who runs it. To use it from another machine, forward its port over SSH (ssh -L ${at}:127.0.0.1:${at} <this machine>), or use presmium serve --host`
+  return `presmium ${mode} listens on this machine only, not on ${listenAddress}: it serves the one user who runs it. To use it from another machine, forward its port over SSH (ssh -L ${at}:127.0.0.1:${at} <this machine>), or use presmium serve --host`
 }
 
 export async function startServer(options: ServerOptions): Promise<PresmiumServer> {
   const env = options.env ?? process.env
   const log = options.log ?? pluginLogger('presmium server')
-  const listenHost = options.host ?? '127.0.0.1'
-  const refused = remoteHost(options.mode, listenHost, options.port)
+  const listenAddress = options.listenAddress ?? '127.0.0.1'
+  const refused = remoteListenRefusal(options.mode, listenAddress, options.port)
   if (refused) throw new Error(refused)
-  const local = machineHosts(listenHost)
+  const basePath = options.publicUrl ? `${new URL(options.publicUrl).pathname.replace(/\/+$/, '')}/` : '/'
+  const inner = (path: string) => basePath !== '/' && path.startsWith(basePath) ? path.slice(basePath.length - 1) : path
+  const machine = machineHosts(listenAddress)
+  const publicHost = options.publicUrl ? normalizeHostName(new URL(options.publicUrl).host) : undefined
+  const local: MachineHosts = publicHost ? host => host === publicHost || machine(host) : machine
 
-  const control = new Control({
+  const control = new ControlChannel({
     policy: options.approvals ?? {},
     timeoutMs: options.approvalTimeoutMs,
   })
-  const token = randomBytes(24).toString('base64url')
-  const mcpTokens = new Map<string, McpCaller>()
-  const mcpStreams = new Map<string, Set<AbortController>>()
   let url = ''
-  const mcpEndpoint: McpEndpoint = {
-    issue(member, mode, issued = {}) {
-      const value = randomBytes(24).toString('base64url')
-      mcpTokens.set(value, { member, mode, ...issued.confirmed ? { confirmed: true } : {}, ...issued.document !== undefined ? { document: issued.document } : {} })
-      return {
-        url: `${url}/mcp`,
-        token: value,
-        revoke: () => {
-          mcpTokens.delete(value)
-          for (const stream of mcpStreams.get(value) ?? []) stream.abort()
-          mcpStreams.delete(value)
-        },
-      }
-    },
-  }
-  const services: [ServiceToken<unknown>, unknown][] = [[APPROVALS, control.approvals], [MCP_ENDPOINT, mcpEndpoint]]
-
-  const serviceToken = env.PRESMIUM_SERVICE_TOKEN || undefined
-  const fromHost = (request: Request) => {
-    const given = bearer(request.headers.get('authorization'))
-    if (!serviceToken || given === undefined || given.length !== serviceToken.length) return false
-    return timingSafeEqual(Buffer.from(given), Buffer.from(serviceToken))
-  }
-  const sessions = new Map<string, ReturnType<McpEndpoint['issue']>>()
+  const mcpTokens = new McpTokens(() => url)
+  const services: [ServiceToken<unknown>, unknown][] = [[APPROVALS, control.approvals], [MCP_ENDPOINT, mcpTokens.endpoint]]
+  const ownServices = new Map(services.map(([token, implementation]) => [token.id, implementation]))
+  const ownService = <T>(token: ServiceToken<T>) => ownServices.get(token.id) as T | undefined
   const focus = new FocusStore()
-  const own = new Map(services.map(([token, impl]) => [token.id, impl]))
-
-  const mounted = new Map<string, Promise<Mounted | undefined>>()
-  const mount = (dir: string) => {
-    let known = mounted.get(dir)
-    if (!known) {
-      known = (async () => {
-        const doc = await options.document(dir)
-        if (!doc) return undefined
-        log.debug(`mounting the server contributions of ${dir || 'the deck'}: ${doc.plugins.filter(p => p.plugin.server).map(p => p.id).join(', ') || 'none'}`)
-        const contributions = new Map<string, ServerContribution>()
-        for (const { id, plugin, config } of doc.plugins) {
-          if (!plugin.server) continue
-          const operatorDir = options.operatorDir ?? doc.operatorDir
-          const ctx: ServerContext = {
-            deckDir: doc.deckDir,
-            workspaceRoot: doc.workspaceRoot,
-            config,
-            settings: (options.settings ?? doc.settings)?.[id] ?? {},
-            lang: doc.lang,
-            service: <T>(token: ServiceToken<T>) => (own.get(token.id) as T | undefined) ?? doc.service(token),
-            secret: name => env[name],
-            ...operatorDir ? { operatorDir } : {},
-            ...doc.home ? { home: true } : {},
-            log: prefixed(log, id),
-          }
-          try {
-            contributions.set(id, await plugin.server.call(plugin, ctx))
-          } catch (error) {
-            log.error(`plugin ${id} failed to make its server contribution: ${errorMessage(error)}`)
-          }
-        }
-        return { doc, contributions }
-      })()
-      const loading = known
-      loading.then((found) => {
-        if (!found && mounted.get(dir) === loading) mounted.delete(dir)
-      }, () => mounted.delete(dir))
-      mounted.set(dir, known)
-    }
-    return known
-  }
+  const diagnostics = options.diagnostics ?? new DiagnosticStore()
+  const mounts = new Mounts({ document: options.document, ownService, settings: options.settings, operatorDir: options.operatorDir, env, diagnostics, log })
 
-  const mcp = options.mcp ? undefined : createPresmiumMcp(serverMcpHost({
+  const mcpHost = serverMcpHost({
     serverHost: options.serverHost,
     control,
     command: options.mode,
-    mount: async dir => (await mount(dir))?.doc,
-    mounted: async () => (await Promise.all([...mounted.values()].map(known => known.catch(() => undefined)))).flatMap(m => (m ? [m.doc] : [])),
-    service: <T>(token: ServiceToken<T>) => own.get(token.id) as T | undefined,
+    mount: async dir => (await mounts.mount(dir))?.doc,
+    mounted: () => mounts.documents(),
+    service: ownService,
     focus,
-  }))
+    diagnostics,
+  })
+  const mcp = options.mcp ? undefined : createPresmiumMcp(mcpHost)
+  const serverRoute = createServerRouteHandler({ control, mcpTokens, focus, diagnostics, mcpHost, serverHost: options.serverHost, launcherToken: env.PRESMIUM_SERVICE_TOKEN || undefined })
 
   const members = new WeakMap<IncomingMessage, Member | Refusal>()
   const memberOf = (req: IncomingMessage): Member | Refusal => {
@@ -232,23 +160,24 @@ export async function startServer(options: ServerOptions): Promise<PresmiumServe
     return found
   }
 
-  const refuse = (refusal: Refusal): Decision => ({ kind: 'answer', response: problem(refusal.status, refusal.message) })
+  const refuse = (refusal: Refusal): Decision => ({ kind: 'answer', response: problemResponse(refusal.status, refusal.message) })
 
   const decide = async (req: IncomingMessage): Promise<Decision> => {
     const url = new URL(req.url ?? '/', 'http://presmium')
-    const path = url.pathname
+    const path = inner(url.pathname)
     const member = memberOf(req)
     if ('status' in member) return refuse(member)
-    const target = pluginPath(path)
+    const target = parsePluginPath(path)
     if (target && !target.plain) return refuse({ status: 400, message: 'a path with a . or .. part or an encoded separator' })
     if (isMcp(path)) return { kind: 'fetch' }
     if (target) {
       if (target.plugin === 'presmium.server') return { kind: 'fetch' }
-      const proxy = await proxyOf(target, documentOf(req.headers, url), member, url.search)
+      if (findRoute(options.serverHost?.routes?.[target.plugin], target.path)) return { kind: 'fetch' }
+      const proxy = await proxyOf(target, requestedDocument(req.headers, url), member, url.search)
       return proxy ?? { kind: 'fetch' }
     }
-    const forward = options.mode === 'serve' ? options.forward?.() : undefined
-    if (!forward) return { kind: 'answer', response: problem(404, 'not found') }
+    const forward = options.mode === 'serve' ? await options.forward?.(url.pathname) : undefined
+    if (!forward) return { kind: 'answer', response: problemResponse(404, 'not found') }
     const site = new URL(forward)
     const lan = !isLoopback(header(req.headers, 'host'))
     const headers = lan ? { host: site.host, ...header(req.headers, 'origin') ? { origin: site.origin } : {} } : undefined
@@ -256,7 +185,7 @@ export async function startServer(options: ServerOptions): Promise<PresmiumServe
   }
 
   const proxyOf = async (target: { plugin: string, path: string, raw: string }, dir: string, member: Member, search: string): Promise<Decision | undefined> => {
-    const contribution = (await mount(dir))?.contributions.get(target.plugin)
+    const contribution = (await mounts.mount(dir))?.contributions.get(target.plugin)
     const found = findProxy(contribution?.proxies, target.path)
     if (!found) return undefined
     const role = found.spec.role ?? 'editor'
@@ -275,118 +204,24 @@ export async function startServer(options: ServerOptions): Promise<PresmiumServe
 
   const serveMcp = async (request: Request): Promise<Response> => {
     const given = bearer(request.headers.get('authorization'))
-    const access: McpCaller | undefined = given === undefined ? undefined : given === token ? { member: LOCAL_AUTHOR, mode: 'author' as const } : mcpTokens.get(given)
-    if (!access) return problem(401, 'MCP needs an Authorization: Bearer token')
-    const limited = await limitBody(request, MAX_BODY)
-    if (limited instanceof Response) return limited
-    request = limited
-    const response = await (options.mcp ? options.mcp(request, access) : mcp!.fetch(request, access))
-    if (given === token || !response.headers.get('content-type')?.startsWith('text/event-stream')) return response
-    if (!mcpTokens.has(given!)) return endedBy(response, AbortSignal.abort(), () => {})
-    const stream = new AbortController()
-    const open = mcpStreams.get(given!) ?? new Set()
-    mcpStreams.set(given!, open.add(stream))
-    return endedBy(response, stream.signal, () => open.delete(stream))
-  }
-
-  const handle = async (request: Request, req: IncomingMessage): Promise<Response> => {
-    const url = new URL(request.url)
-    const path = url.pathname
-    const member = memberOf(req)
-    if ('status' in member) return problem(member.status, member.message)
-    const document = documentOf(req.headers, url)
-    if (isMcp(path)) return serveMcp(request)
-    if (path.startsWith(`${SERVER_PATH}/`)) return await serverRoute(request, path.slice(SERVER_PATH.length + 1), member, document, req)
-    const target = pluginPath(path)
-    if (!target) return problem(404, 'not found')
-    return await pluginRoute(request, target, member, document)
-  }
-
-  const serverRoute = async (request: Request, route: string, member: Member, document: string, req: IncomingMessage): Promise<Response> => {
-    if (route === 'hello') return json({ member, document })
-    if (route === 'control') {
-      if (request.method === 'GET') {
-        const window = new URL(request.url).searchParams.get('window') || randomUUID()
-        const stream = control.open(window, member, document)
-        req.once('close', () => stream.close())
-        return eventStream(stream, request.signal)
-      }
-      if (request.method !== 'POST') return problem(405, 'GET or POST')
-      const limited = await limitBody(request, MAX_BODY)
-      if (limited instanceof Response) return limited
-      const body: unknown = await limited.json().catch(() => undefined)
-      if (!isRecord(body)) return problem(400, 'a JSON object')
-      if (body.type === 'answer' && typeof body.id === 'string') {
-        const status = control.answer(body.id, body.allow === true, member)
-        return status === 200 ? json({ ok: true }) : problem(status, status === 404 ? 'no such approval' : 'this member may not answer this approval')
-      }
-      if (body.type === 'report' && typeof body.window === 'string') {
-        const position = windowPosition(body.position)
-        const ok = control.report(body.window, member, { position, role: typeof body.role === 'string' ? body.role : undefined, status: isRecord(body.status) ? body.status : undefined })
-        return ok ? json({ ok: true }) : problem(404, 'unknown window')
-      }
-      return problem(400, 'unknown message')
-    }
-    if (route === 'tokens') return await tokensRoute(request)
-    if (route === 'focus') return await focusRoute(request)
-    return problem(404, 'not found')
-  }
-
-  const tokensRoute = async (request: Request): Promise<Response> => {
-    if (!serviceToken) return problem(403, 'session tokens are issued only to the host that started this service (PRESMIUM_SERVICE_TOKEN)')
-    if (!fromHost(request)) return problem(401, 'session tokens need Authorization: Bearer <the service token>')
-    const limited = await limitBody(request, MAX_BODY)
-    if (limited instanceof Response) return limited
-    const body: unknown = await limited.json().catch(() => ({}))
-    const session = isRecord(body) && typeof body.session === 'string' && body.session !== '' ? body.session : undefined
-    if (request.method === 'DELETE') {
-      const revoked = session === undefined ? [...sessions.keys()] : sessions.has(session) ? [session] : []
-      for (const id of revoked) {
-        sessions.get(id)!.revoke()
-        sessions.delete(id)
-      }
-      return json({ revoked: revoked.length })
-    }
-    if (request.method !== 'POST') return problem(405, 'POST or DELETE')
-    if (!isRecord(body) || typeof body.document !== 'string' || session === undefined) return problem(400, '{ document, session }')
-    const document = body.document
-    if (options.serverHost && !(await options.serverHost.documents()).some(doc => doc.dir === document)) return problem(404, `no document ${JSON.stringify(document)}`)
-    sessions.get(session)?.revoke()
-    const grant = mcpEndpoint.issue(LOCAL_AUTHOR, 'author', { confirmed: true, document })
-    sessions.set(session, grant)
-    return json({ url: grant.url, token: grant.token, document }, 201)
-  }
-
-  const focusRoute = async (request: Request): Promise<Response> => {
-    if (request.method === 'GET') {
-      const params = new URL(request.url).searchParams
-      const found = focus.get(params.has('document') ? params.get('document')! : undefined)
-      return json(found ? { document: found.document, focus: found.focus, reported: new Date(found.at).toISOString() } : { focus: null })
-    }
-    if (request.method !== 'POST') return problem(405, 'GET or POST')
-    if (serviceToken && !fromHost(request)) return problem(401, 'a focus report needs Authorization: Bearer <the service token>')
-    if (!options.serverHost) return problem(409, 'this server compiles no document')
+    const caller = mcpTokens.callerOf(given)
+    if (!caller) return problemResponse(401, 'MCP needs an Authorization: Bearer token')
     const limited = await limitBody(request, MAX_BODY)
     if (limited instanceof Response) return limited
-    const body = focusBody(await limited.json().catch(() => undefined))
-    if (typeof body === 'string') return problem(400, body)
-    if (!(await options.serverHost.documents()).some(doc => doc.dir === body.document)) return problem(404, `no document ${JSON.stringify(body.document)}`)
-    try {
-      const { doc } = await options.serverHost.compile(body.document)
-      const record = focus.report(body.document, doc, body.focus)
-      return json({ document: record.document, focus: record.focus, reported: new Date(record.at).toISOString() })
-    } catch (error) {
-      return problem(400, errorMessage(error))
-    }
+    const response = await (options.mcp ? options.mcp(limited, caller) : mcp!.fetch(limited, caller))
+    return mcpTokens.tieToGrant(given!, response)
   }
 
   const pluginRoute = async (request: Request, target: { plugin: string, path: string }, member: Member, document: string): Promise<Response> => {
-    const known = await mount(document)
-    if (!known) return problem(404, `no document ${JSON.stringify(document)}`)
-    const found = findRoute(known.contributions.get(target.plugin)?.routes, target.path)
-    if (!found) return problem(404, 'not found')
+    let found = findRoute(options.serverHost?.routes?.[target.plugin], target.path)
+    if (!found) {
+      const known = await mounts.mount(document)
+      if (!known) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+      found = findRoute(known.contributions.get(target.plugin)?.routes, target.path)
+    }
+    if (!found) return problemResponse(404, 'not found')
     const role = found.route.role ?? 'editor'
-    if (!hasRole(member, role)) return problem(403, `this route needs the role ${role}`)
+    if (!hasRole(member, role)) return problemResponse(403, `this route needs the role ${role}`)
     const limited = await limitBody(request, found.route.maxBody ?? MAX_BODY)
     if (limited instanceof Response) return limited
     try {
@@ -394,52 +229,67 @@ export async function startServer(options: ServerOptions): Promise<PresmiumServe
       return response.headers.has('cache-control') ? response : withHeaders(response, { 'Cache-Control': 'no-store' })
     } catch (error) {
       log.error(`route ${target.plugin}/${target.path} failed: ${errorMessage(error)}`)
-      return problem(500, errorMessage(error))
+      return problemResponse(500, errorMessage(error))
     }
   }
 
-  const proxy = createProxy()
-  const server = nodeServer({ decide, decideUpgrade, fetch: handle, proxy })
-  const port = await listen(server, options.port ?? (options.mode === 'dev' ? 0 : 4310), listenHost)
-  url = `http://${urlHost(listenHost)}:${port}`
-  log.debug(`listening at ${url}`)
-  if (options.stateFile) {
-    mkdirSync(dirname(options.stateFile), { recursive: true })
-    writeFileSync(options.stateFile, `${JSON.stringify({ url, mcp: `${url}/mcp`, token, pid: process.pid }, null, 2)}\n`, { mode: 0o600 })
-    chmodSync(options.stateFile, 0o600)
+  const handle = async (request: Request, req: IncomingMessage): Promise<Response> => {
+    const url = new URL(request.url)
+    const path = inner(url.pathname)
+    const member = memberOf(req)
+    if ('status' in member) return problemResponse(member.status, member.message)
+    const document = requestedDocument(req.headers, url)
+    if (isMcp(path)) return serveMcp(request)
+    if (path.startsWith(`${SERVER_PATH}/`)) return await serverRoute(request, path.slice(SERVER_PATH.length + 1), { member, document, req })
+    const target = parsePluginPath(path)
+    if (!target) return problemResponse(404, 'not found')
+    return await pluginRoute(request, target, member, document)
   }
 
-  const takeDown = async (known: Promise<Mounted | undefined>) => {
-    for (const [id, contribution] of (await known.catch(() => undefined))?.contributions ?? []) {
-      await Promise.resolve(contribution.close?.()).catch((error: unknown) => log.error(`the contribution of ${id} failed to close: ${errorMessage(error)}`))
+  const proxy = createProxy()
+  const http = nodeServer({ decide, decideUpgrade, fetch: handle, proxy })
+  let closing: Promise<void> | undefined
+  const close = (): Promise<void> => closing ??= Promise.resolve().then(async () => {
+    mounts.stop()
+    mcpTokens.revokeAgentSessions()
+    control.close()
+    await mcp?.close().catch((error: unknown) => log.error(`MCP failed to close: ${errorMessage(error)}`))
+    try {
+      await mounts.close()
+    } finally {
+      try { proxy.close() }
+      finally { await http.close() }
+    }
+  })
+  let port: number
+  try {
+    port = await listen(http.server, options.port ?? (options.mode === 'dev' ? 0 : 4310), listenAddress)
+    url = `http://${urlHost(listenAddress)}:${port}`
+    log.debug(`listening at ${url}`)
+    if (options.stateFile) {
+      mkdirSync(dirname(options.stateFile), { recursive: true })
+      writeFileSync(options.stateFile, `${JSON.stringify({ url, mcp: `${url}/mcp`, token: mcpTokens.processMcpToken, pid: process.pid }, null, 2)}\n`, { mode: 0o600 })
+      chmodSync(options.stateFile, 0o600)
     }
+  } catch (error) {
+    await close().catch((cleanup: unknown) => log.error(`the server failed to close after startup failed: ${errorMessage(cleanup)}`))
+    throw error
   }
 
   return {
     url,
+    publicUrl: options.publicUrl?.replace(/\/+$/, '') ?? url,
     port,
-    token,
+    mcpToken: mcpTokens.processMcpToken,
     services,
     control,
     serverHost: options.serverHost,
-    async unmount(dir) {
-      focus.forget(dir)
-      const known = mounted.get(dir)
-      mounted.delete(dir)
-      if (known) {
-        log.debug(`unmounting the server contributions of ${dir || 'the deck'}`)
-        await takeDown(known)
-      }
-    },
-    async close() {
-      for (const grant of sessions.values()) grant.revoke()
-      sessions.clear()
-      control.close()
-      await mcp?.close().catch((error: unknown) => log.error(`MCP failed to close: ${errorMessage(error)}`))
-      for (const known of mounted.values()) await takeDown(known)
-      proxy.close()
-      await closeServer(server)
+    diagnostics,
+    async unmount(dir, unmountOptions = {}) {
+      if (!unmountOptions.preserveFocus) focus.forget(dir)
+      await mounts.unmount(dir)
     },
+    close,
   }
 }
 
@@ -455,15 +305,3 @@ function withHeaders(response: Response, headers: Record<string, string>): Respo
   }
   return response
 }
-
-function windowPosition(value: unknown): WindowPosition | undefined {
-  if (!isRecord(value) || typeof value.slide !== 'number' || typeof value.step !== 'number') return undefined
-  const { trail } = value
-  return {
-    slide: value.slide,
-    step: value.step,
-    ...typeof value.view === 'string' ? { view: value.view } : {},
-    ...typeof value.section === 'string' ? { section: value.section } : {},
-    ...Array.isArray(trail) && trail.length <= 10_000 && trail.every(key => typeof key === 'string') ? { trail: trail as string[] } : {},
-  }
-}

package/src/host.ts

@@ -1,52 +0,0 @@
-import type { Compilation } from '@lincyaw/compiler'
-import { pluginId } from '@lincyaw/compiler'
-import type { Finding, IRDocument, PresmiumNodePlugin, RunResult, ServiceToken } from '@lincyaw/kernel'
-
-export interface ServedPlugin {
-  id: string
-  plugin: PresmiumNodePlugin
-  config: Record<string, unknown>
-}
-
-export interface ServedDocument {
-  deckDir: string
-  workspaceRoot: string
-  lang?: string
-  plugins: ServedPlugin[]
-  service<T>(token: ServiceToken<T>): T | undefined
-  settings?: Record<string, Record<string, unknown>>
-  operatorDir?: string
-  home?: boolean
-}
-
-export function servedDocument(compilation: Compilation): ServedDocument {
-  const { presmium } = compilation.doc.config
-  return {
-    deckDir: compilation.deckDir,
-    workspaceRoot: compilation.workspaceRoot,
-    lang: compilation.doc.meta.lang,
-    plugins: compilation.plugins.flatMap((loaded) => {
-      if (!loaded.plugin) return []
-      const config = presmium[pluginId(loaded)]
-      return [{ id: pluginId(loaded), plugin: loaded.plugin, config: config !== null && typeof config === 'object' && !Array.isArray(config) ? config as Record<string, unknown> : {} }]
-    }),
-    service: compilation.service,
-    settings: compilation.settings,
-    ...compilation.operatorDir ? { operatorDir: compilation.operatorDir } : {},
-  }
-}
-
-export interface HostDocument {
-  dir: string
-  title: string
-  lang?: string
-  tags?: string[]
-}
-
-export interface ServerHost {
-  documents(): Promise<HostDocument[]>
-  compile(document: string): Promise<{ doc: IRDocument, diagnostics: Finding[] }>
-  check(document: string): Promise<Finding[]>
-  build(document: string, options?: { to?: string[] }): Promise<{ outputs: { renderer: string, outDir: string }[], findings: Finding[] }>
-  run(document: string, target: { section: string, block: string }, signal?: AbortSignal): Promise<RunResult>
-}

package/src/mcp.ts

@@ -1,64 +0,0 @@
-import type { AgentTool, Member, ServiceToken } from '@lincyaw/kernel'
-import type { McpHost, McpPluginTools, McpPosition } from '@lincyaw/mcp'
-import type { Control } from './control.ts'
-import type { FocusStore } from './focus.ts'
-import type { ServedDocument, ServerHost } from './host.ts'
-
-export interface McpHostOptions {
-  serverHost?: ServerHost
-  control: Control
-  command: 'dev' | 'serve'
-  mount(document: string): Promise<ServedDocument | undefined>
-  mounted(): Promise<ServedDocument[]>
-  service<T>(token: ServiceToken<T>): T | undefined
-  focus: FocusStore
-}
-
-function toolsOf(documents: ServedDocument[], own: McpHostOptions['service']): McpPluginTools {
-  const tools = new Map<string, AgentTool>()
-  for (const doc of documents) {
-    for (const { plugin } of doc.plugins) for (const tool of plugin.tools ?? []) if (!tools.has(tool.name)) tools.set(tool.name, tool)
-  }
-  const doc = documents[0]
-  return { tools: [...tools.values()], service: <T>(token: ServiceToken<T>) => own(token) ?? doc?.service(token) }
-}
-
-export function serverMcpHost(options: McpHostOptions): McpHost {
-  const { control } = options
-  const host = (): ServerHost => {
-    if (!options.serverHost) throw new Error('this server has no host operations')
-    return options.serverHost
-  }
-  const position = (entry: ReturnType<Control['positions']>[number]): McpPosition => {
-    const { report } = entry
-    const { slide, step, view, section, trail } = report.position!
-    return { document: entry.document, member: entry.member, slide, step, view, ...section === undefined ? {} : { section }, ...trail ? { trail } : {}, role: report.role, at: report.at }
-  }
-  return {
-    process: { command: options.command },
-    documents: () => host().documents(),
-    compile: document => host().compile(document),
-    check: document => host().check(document),
-    build: (document, build) => host().build(document, build),
-    run: (document, target, signal) => host().run(document, target, signal),
-    approve: (request, signal) => control.approvals.request(request, signal),
-    offers: kind => control.policy(kind) !== 'off',
-    approval: kind => control.policy(kind),
-    async tools(document) {
-      if (document === undefined) return toolsOf(await options.mounted(), options.service)
-      const doc = await options.mount(document)
-      return toolsOf(doc ? [doc] : [], options.service)
-    },
-    positions(document: string | undefined, member: Member) {
-      const all = control.positions(undefined, document, member)
-      const presenting = (w: typeof all[number]) => w.member === member.id && (w.report.role === 'presenter' || w.report.role === 'audience')
-      return [...all.filter(presenting), ...all.filter(w => !presenting(w))].map(position)
-    },
-    watchPositions: listener => control.watch(listener),
-    focus: document => options.focus.get(document),
-    watchFocus: listener => options.focus.watch(listener),
-    classroom: document => control.status(document),
-    navigate: (document, to, member) => control.go(to, member, document),
-    session: (document, action, name, member) => control.session(action, name, document, member),
-  }
-}