feat: awareness for collaboration

.github/workflows/test.yml

@@ -26,4 +26,7 @@ jobs:
 
       - run: make container
 
-      # TODO: tests
+      # Virtual display for VS Code tests
+      - run: sudo apt-get update && sudo apt-get install --yes xvfb
+
+      - run: xvfb-run --auto-servernum npm --workspace vscode-workbench run test

collab-server/src/server.ts

@@ -90,7 +90,18 @@ server.httpServer.listen(socketPath, () => {
 
 await Promise.race([once(process, 'SIGINT'), once(process, 'SIGQUIT'), once(process, 'SIGTERM')])
 console.log('Hocuspocus shutting down..')
+
+// Persist open documents to disk.
+await Promise.all(
+  [...server.hocuspocus.documents.values()].map(async doc => {
+    try {
+      await fs.writeFile(checkedToDiskPath(doc.name), doc.getText(YTEXT_KEY).toString())
+      console.log(`Saved '${doc.name}' to disk`)
+    } catch (e) {
+      console.error(`Failed to save '${doc.name}' to disk:`, e)
+    }
+  }),
+)
+
 await server.destroy()
 db.close()
-
-// TODO: ensure writes are flushed to disk.

package.json

@@ -19,6 +19,7 @@
     "lint": "prettier --check . && eslint"
   },
   "dependencies": {
+    "@hocuspocus/provider": "^4.0.0",
     "@prisma/adapter-better-sqlite3": "^7.7.0",
     "@prisma/client": "^7.7.0",
     "better-auth": "^1.6.2",
@@ -28,13 +29,15 @@
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "swr": "^2.4.1",
+    "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@types/ws": "^8.18.1",
     "babel-plugin-react-compiler": "1.0.0",
     "concurrently": "^9.2.1",
     "eslint": "^9",

src/app/AvatarMenu.tsx

@@ -1,9 +1,9 @@
 'use client'
 
+import AvatarIcon from '@/app/components/AvatarIcon'
 import authClient from '@/lib/auth-client'
 import { ConfigCtx } from '@/lib/contexts'
 import { setIsAdmin } from '@/lib/server/actions'
-import Image from 'next/image'
 import Link from 'next/link'
 import { useRouter } from 'next/navigation'
 import { useContext } from 'react'
@@ -19,13 +19,7 @@ export default function AvatarMenu() {
       <>
         {user.isAdmin && <span className='admin-badge'>admin</span>}
         <div className='avatar-menu'>
-          <button className='avatar-btn'>
-            {user.image ? (
-              <Image src={user.image} alt={user.name} width={28} height={28} loading='eager' />
-            ) : (
-              <span className='avatar-placeholder'>{user.name[0].toUpperCase()}</span>
-            )}
-          </button>
+          <AvatarIcon user={user} />
           <div className='avatar-dropdown'>
             <div className='avatar-dropdown-user'>{user.name}</div>
             {user.isAdmin && <Link href='/admin'>Admin interface</Link>}

src/app/NavbarExtra.tsx

@@ -0,0 +1,38 @@
+'use client'
+
+import React, { createContext, type ReactNode, type RefObject, use, useLayoutEffect, useRef, useState } from 'react'
+
+type Setter = (_: ReactNode) => void
+const NavbarExtraSetCtx = createContext<RefObject<Setter> | null>(null)
+
+export function NavbarExtraProvider({ children }: Readonly<{ children: ReactNode }>) {
+  const ref = useRef<Setter>(() => {
+    console.warn('useNavbarExtra called before <NavbarExtra /> mounted')
+  })
+  return <NavbarExtraSetCtx value={ref}>{children}</NavbarExtraSetCtx>
+}
+
+/** Renders extra contents of the navbar as set by specific pages.
+ * This component and the page that uses {@link SetNavbarExtra}
+ * must share a {@link NavbarExtraProvider} parent */
+export function NavbarExtra() {
+  const [extra, setExtra] = useState<ReactNode>(null)
+  const ref = use(NavbarExtraSetCtx)!
+  useLayoutEffect(() => {
+    ref.current = setExtra
+  }, [ref, setExtra])
+  return extra
+}
+
+/** Sets extra contents of the navbar to its children. */
+export function SetNavbarExtra({ children }: Readonly<{ children: ReactNode }>) {
+  const ref = use(NavbarExtraSetCtx)!
+  React.useEffect(() => {
+    ref.current(children)
+    return () => {
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      ref.current(null)
+    }
+  }, [ref, children])
+  return null
+}

src/app/[userName]/[projectName]/page.tsx

@@ -1,6 +1,7 @@
 import { requireAuth } from '@/lib/server/actions'
 import { getDb } from '@/lib/server/db'
 import { getEditorSessionManager } from '@/lib/server/editorSessions'
+import { canAccessProject } from '@/lib/server/util'
 import z from 'zod'
 
 const zParams = z.object({
@@ -48,8 +49,7 @@ export default async function EditorSession({ params: params_ }: { params: Promi
   const project = await db.project.findUnique({
     where: { userId_name: { userId: owner.id, name: params.projectName } },
   })
-  const isOwner = viewer.name === params.userName
-  if (!project || (!isOwner && !project.isPublic)) {
+  if (!project || !canAccessProject(viewer, project)) {
     return <Error msg='Project not found' />
   }
 

src/app/api/setup-events/route.ts

@@ -1,41 +1,29 @@
 import { getSeedState } from '@/lib/server/seed'
+import { sseStreamResponse } from '@/lib/server/util'
 
 export async function GET() {
-  const encoder = new TextEncoder()
-
+  // eslint-disable-next-line prefer-const
   let interval: ReturnType<typeof setInterval> | undefined
-  const stream = new ReadableStream({
-    start(controller) {
-      let cursor = 0
-
-      interval = setInterval(() => {
-        const st = getSeedState()
-        while (cursor < st.events.length) {
-          const event = st.events[cursor++]
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`))
-          if (event.type === 'done' || event.type === 'error') {
-            clearInterval(interval)
-            controller.close()
-            return
-          }
-        }
-        if (!st.inProgress) {
-          clearInterval(interval)
-          controller.close()
-        }
-      }, 500)
-    },
-    cancel() {
-      clearInterval(interval)
-    },
+  const [response, send, close] = sseStreamResponse(() => {
+    clearInterval(interval)
   })
+  let cursor = 0
+  interval = setInterval(() => {
+    const st = getSeedState()
+    while (cursor < st.events.length) {
+      const event = st.events[cursor++]
+      send(event)
+      if (event.type === 'done' || event.type === 'error') {
+        clearInterval(interval)
+        close()
+        return
+      }
+    }
+    if (!st.inProgress) {
+      clearInterval(interval)
+      close()
+    }
+  }, 500)
 
-  return new Response(stream, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      Connection: 'keep-alive',
-      'X-Accel-Buffering': 'no',
-    },
-  })
+  return response
 }

src/app/components/AvatarIcon.tsx

@@ -0,0 +1,14 @@
+import type { User } from '@/lib/server/auth'
+import Image from 'next/image'
+
+export default function AvatarIcon({ user }: { user: Pick<User, 'name' | 'image'> }) {
+  return (
+    <button className='avatar-btn'>
+      {user.image ? (
+        <Image src={user.image} alt={user.name} width={28} height={28} loading='eager' />
+      ) : (
+        <span className='avatar-placeholder'>{user.name[0].toUpperCase()}</span>
+      )}
+    </button>
+  )
+}

src/app/layout.tsx

@@ -9,6 +9,7 @@ import { connection } from 'next/server'
 import { Suspense, type ReactNode } from 'react'
 import AvatarMenu from './AvatarMenu'
 import Breadcrumbs from './Breadcrumbs'
+import { NavbarExtra, NavbarExtraProvider } from './NavbarExtra'
 
 const openSans = Open_Sans({
   subsets: ['latin'],
@@ -56,18 +57,21 @@ async function RootLayoutBody({
     <html lang='en' className={openSans.className}>
       {/* https://nextjs.org/docs/app/getting-started/server-and-client-components#interleaving-server-and-client-components */}
       <ConfigCtx value={clientCfg}>
-        <body>
-          <nav>
-            <Link className='logo' href='/'>
-              <Image src='/static/lean-logo.svg' alt='Lean logo' width={70} height={16} loading='eager' />
-              <span className='logo-text'>Lean Workbench</span>
-            </Link>
-            <Breadcrumbs />
-            <span className='spacer'></span>
-            {serverCfg.isSetupComplete && <AvatarMenu />}
-          </nav>
-          <main style={{ maxWidth: '600px' }}>{children}</main>
-        </body>
+        <NavbarExtraProvider>
+          <body>
+            <nav>
+              <Link className='logo' href='/'>
+                <Image src='/static/lean-logo.svg' alt='Lean logo' width={70} height={16} loading='eager' />
+                <span className='logo-text'>Lean Workbench</span>
+              </Link>
+              <Breadcrumbs />
+              <span className='spacer'></span>
+              <NavbarExtra />
+              {serverCfg.isSetupComplete && <AvatarMenu />}
+            </nav>
+            <main style={{ maxWidth: '600px' }}>{children}</main>
+          </body>
+        </NavbarExtraProvider>
       </ConfigCtx>
     </html>
   )

src/lib/server/collabServer.ts

@@ -18,6 +18,8 @@ export class CollabServerHandle {
   readonly uuid = crypto.randomUUID()
   /** Directory in which `collab-server` places its files. */
   readonly workDir: string = `/tmp/collab-server-${this.uuid}/`
+  /** Path to the `collab-server` UDS file. */
+  readonly socketPath: string = path.join(this.workDir, COLLAB_SOCKET_FILENAME)
 
   constructor(
     /** Project that this server manages. */

src/lib/server/editorSessions.ts

@@ -1,9 +1,9 @@
-import { User } from '@/lib/server/auth'
+import type { User } from '@/lib/server/auth'
 import { CollabServerHandle } from '@/lib/server/collabServer'
 import { getWorkspacesDir } from '@/lib/server/config'
 import { getDb } from '@/lib/server/db'
 import { VscodeServerHandle } from '@/lib/server/vscodeServer'
-import { Project } from '@/prisma/generated/client'
+import type { Project } from '@/prisma/generated/client'
 import path from 'node:path'
 import { EventEmitter } from 'node:stream'
 import 'server-only'

src/lib/server/util.ts

@@ -1,5 +1,7 @@
+import type { Project } from '@/prisma/generated/client'
 import fs from 'node:fs/promises'
 import 'server-only'
+import type { User } from './auth'
 
 export interface ProcessInfo {
   pid: number
@@ -61,3 +63,45 @@ export const BWRAP_ARGS =
 export function bwrapProjectDir(projectName: string) {
   return `/workspace/${projectName}/`
 }
+
+export function canAccessProject(user: User, project: Project) {
+  const isOwner = user.id === project.userId
+  return isOwner || project.isPublic
+}
+
+/** Returns `[response, send, close]`.
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events */
+export function sseStreamResponse(onCancel?: () => void): [Response, (msg: object) => void, () => void] {
+  let send: (msg: object) => void = () => {}
+  let close: () => void = () => {}
+  let closed = false
+  const encoder = new TextEncoder()
+  const stream = new ReadableStream({
+    start(controller) {
+      send = msg => {
+        if (closed) return
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(msg)}\n\n`))
+      }
+      close = () => {
+        if (closed) return
+        closed = true
+        controller.close()
+      }
+    },
+    cancel() {
+      closed = true
+      if (onCancel) onCancel()
+    },
+  })
+
+  const response = new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  })
+
+  return [response, send, close]
+}