zooid 0.6.1 → 0.7.1

package/src/prepull-images.ts

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const pExecFile = promisify(execFile)
+
+export interface PrepullExec {
+  (cmd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }>
+}
+
+export interface PrepullOptions {
+  engine: 'docker' | 'podman'
+  runtime: 'local' | 'docker' | 'podman'
+  /** Injectable for tests. Defaults to a child_process.execFile-backed exec. */
+  exec?: PrepullExec
+  /** When true, skip the inspect check and pull every image. */
+  refresh?: boolean
+  /** When true, the function returns immediately without touching the engine. */
+  skip?: boolean
+  log?: (line: string) => void
+}
+
+export interface PrepullableRegistry {
+  agentNames(): string[]
+  resolveSpawnImage(name: string): string | undefined
+}
+
+/**
+ * Walk the registry's unique resolved-image set, `<engine> image inspect`
+ * each one, and `<engine> pull` the ones not cached locally. Parallel and
+ * fail-fast: any pull exit ≠ 0 throws with the engine's stderr embedded.
+ * No-op when `opts.skip` or `opts.runtime === 'local'`.
+ */
+export async function prepullImages(
+  registry: PrepullableRegistry,
+  opts: PrepullOptions,
+): Promise<void> {
+  if (opts.skip || opts.runtime === 'local') return
+  const exec = opts.exec ?? defaultExec
+  const log = opts.log ?? ((l: string) => console.log(l))
+
+  const images = new Set<string>()
+  for (const name of registry.agentNames()) {
+    const img = registry.resolveSpawnImage(name)
+    if (img) images.add(img)
+  }
+
+  const toPull: string[] = []
+  let cached = 0
+  if (opts.refresh) {
+    toPull.push(...images)
+  } else {
+    await Promise.all(
+      [...images].map(async (img) => {
+        const r = await exec(opts.engine, ['image', 'inspect', img])
+        if (r.code === 0) cached++
+        else toPull.push(img)
+      }),
+    )
+  }
+
+  log(
+    `[zooid] image prepull: ${images.size} unique images (${cached} cached, ${toPull.length} to pull)`,
+  )
+  if (toPull.length === 0) return
+
+  await Promise.all(
+    toPull.map(async (img) => {
+      log(`[zooid]   ${img}  pulling…`)
+      const start = Date.now()
+      const r = await exec(opts.engine, ['pull', img])
+      const secs = ((Date.now() - start) / 1000).toFixed(1)
+      if (r.code !== 0) {
+        throw new Error(
+          `image prepull failed for ${img}:\n${r.stderr.trim() || '(no stderr)'}`,
+        )
+      }
+      log(`[zooid]   ${img}  ✓ ${secs}s`)
+    }),
+  )
+}
+
+const defaultExec: PrepullExec = async (cmd, args) => {
+  try {
+    const { stdout, stderr } = await pExecFile(cmd, args, {
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    return { code: 0, stdout, stderr }
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & {
+      code?: number | string
+      stdout?: string
+      stderr?: string
+    }
+    return {
+      code: typeof e.code === 'number' ? e.code : 1,
+      stdout: e.stdout ?? '',
+      stderr: e.stderr ?? String(e),
+    }
+  }
+}

package/src/services/tuwunel.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { buildRunArgs } from './tuwunel.js'
+
+describe('buildRunArgs', () => {
+  const base = {
+    name: 'zooid-tuwunel',
+    image: 'ghcr.io/matrix-construct/tuwunel:latest',
+    hostPort: 8448,
+    paths: {
+      dataDir: '/abs/data/matrix',
+      dbDir: '/abs/data/matrix/db',
+      mediaDir: '/abs/data/matrix/media',
+      configDir: '/abs/data/matrix/config',
+      registrationsDir: '/abs/data/matrix/config/registrations',
+      tuwunelTomlPath: '/abs/data/matrix/config/tuwunel.toml',
+      appserviceYamlPath: '/abs/data/matrix/config/registrations/zooid.yaml',
+      envPath: '/abs/data/matrix/config/.env',
+    },
+  }
+
+  it('uses docker by default, mounts persistent volumes and config read-only', () => {
+    const args = buildRunArgs({ ...base, engine: 'docker' })
+    expect(args[0]).toBe('run')
+    expect(args).toContain('--rm')
+    // Foregrounded so the parent process owns Tuwunel's stdio (logs).
+    expect(args).not.toContain('-d')
+    expect(args).toContain('--name')
+    expect(args).toContain('zooid-tuwunel')
+    expect(args).toContain('-p')
+    expect(args).toContain('8448:8448')
+    expect(args).toContain('/abs/data/matrix/db:/var/lib/tuwunel/db')
+    expect(args).toContain('/abs/data/matrix/media:/var/lib/tuwunel/media')
+    expect(args).toContain(
+      '/abs/data/matrix/config/tuwunel.toml:/etc/tuwunel/tuwunel.toml:ro',
+    )
+    expect(args).toContain(
+      '/abs/data/matrix/config/registrations:/var/lib/tuwunel/registrations:ro',
+    )
+    // ZOD041 deliberately does NOT mount ${dataRoot}/logs into the container.
+    // Today the daemon captures tuwunel's stdout/stderr via captureChildToFile
+    // — there's no internal tuwunel log directive yet. A future cycle that flips
+    // tuwunel.toml to write its own logs can add the mount alongside that change.
+    expect(args.some((a) => a.endsWith(':/var/log/tuwunel'))).toBe(false)
+    expect(args).toContain('TUWUNEL_CONFIG=/etc/tuwunel/tuwunel.toml')
+    expect(args[args.length - 1]).toBe(base.image)
+  })
+
+  it('engine: podman switches the binary (caller chooses), args are identical', () => {
+    const docker = buildRunArgs({ ...base, engine: 'docker' })
+    const podman = buildRunArgs({ ...base, engine: 'podman' })
+    expect(podman).toEqual(docker)
+  })
+
+  it('honors a custom container name and host port', () => {
+    const args = buildRunArgs({
+      ...base,
+      name: 'my-zooid-tuwunel',
+      hostPort: 9000,
+      engine: 'docker',
+    })
+    expect(args).toContain('my-zooid-tuwunel')
+    expect(args).toContain('9000:8448')
+  })
+})

package/src/services/tuwunel.ts

@@ -0,0 +1,91 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import type { Paths } from '../bootstrap/paths.js'
+
+export interface TuwunelOpts {
+  name: string
+  image?: string
+  hostPort: number
+  paths: Paths
+  engine: 'docker' | 'podman'
+}
+
+const DEFAULT_IMAGE = 'ghcr.io/matrix-construct/tuwunel:latest'
+
+export function buildRunArgs(opts: TuwunelOpts): string[] {
+  const image = opts.image ?? DEFAULT_IMAGE
+  return [
+    'run',
+    '--rm',
+    '--name',
+    opts.name,
+    '-p',
+    `${opts.hostPort}:8448`,
+    '-v',
+    `${opts.paths.dbDir}:/var/lib/tuwunel/db`,
+    '-v',
+    `${opts.paths.mediaDir}:/var/lib/tuwunel/media`,
+    '-v',
+    `${opts.paths.tuwunelTomlPath}:/etc/tuwunel/tuwunel.toml:ro`,
+    '-v',
+    `${opts.paths.registrationsDir}:/var/lib/tuwunel/registrations:ro`,
+    '-e',
+    'TUWUNEL_CONFIG=/etc/tuwunel/tuwunel.toml',
+    image,
+  ]
+}
+
+export class TuwunelService {
+  private child: ChildProcess | null = null
+  constructor(private readonly opts: TuwunelOpts) {}
+
+  start(): ChildProcess {
+    this.child = spawn(this.opts.engine, buildRunArgs(this.opts), {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return this.child
+  }
+
+  async stop(): Promise<void> {
+    // Foregrounded container: kill the engine process; --rm cleans up after.
+    if (this.child && this.child.exitCode === null) {
+      this.child.kill('SIGTERM')
+      await new Promise<void>((resolve) => {
+        this.child!.on('exit', () => resolve())
+      })
+    }
+    this.child = null
+    // Defensive: the parent may have died while the container was running, in
+    // which case --rm doesn't fire. `<engine> stop` is a no-op if it's already
+    // gone (errors are swallowed).
+    await execEngine(this.opts.engine, ['stop', this.opts.name]).catch(() => {})
+  }
+
+  async waitHealthy(opts: { url: string; timeoutMs: number }): Promise<void> {
+    const deadline = Date.now() + opts.timeoutMs
+    while (Date.now() < deadline) {
+      try {
+        const r = await fetch(`${opts.url}/_matrix/client/versions`)
+        if (r.ok) return
+      } catch {
+        // not yet
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500))
+    }
+    throw new Error(
+      `Tuwunel did not become healthy at ${opts.url} in ${opts.timeoutMs}ms`,
+    )
+  }
+}
+
+function execEngine(engine: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(engine, args, { stdio: 'pipe' })
+    let stderr = ''
+    child.stderr.on('data', (b) => (stderr += String(b)))
+    child.on('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${engine} ${args.join(' ')} failed: ${stderr.trim()}`))
+    })
+    child.on('error', reject)
+  })
+}

package/src/web/resolve.test.ts

@@ -0,0 +1,50 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { resolveWebRoot, webSourcePackage } from './resolve.js'
+
+let root: string
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'zooid-resolve-'))
+})
+afterEach(() => rmSync(root, { recursive: true, force: true }))
+
+describe('resolveWebRoot', () => {
+  it('returns dist/web when present (published-package layout)', () => {
+    const distWeb = join(root, 'dist', 'web')
+    mkdirSync(distWeb, { recursive: true })
+    writeFileSync(join(distWeb, 'index.html'), '<html/>')
+    expect(resolveWebRoot(root)).toBe(distWeb)
+  })
+
+  it('falls back to ../../zoon/packages/web/dist when running from source', () => {
+    const cliRoot = join(root, 'zooid', 'packages', 'cli')
+    mkdirSync(cliRoot, { recursive: true })
+    const webPkg = join(root, 'zoon', 'packages', 'web')
+    const webDist = join(webPkg, 'dist')
+    mkdirSync(webDist, { recursive: true })
+    writeFileSync(join(webPkg, 'package.json'), '{"name":"@zoon/web"}')
+    writeFileSync(join(webDist, 'index.html'), '<html/>')
+    expect(resolveWebRoot(cliRoot)).toBe(webDist)
+  })
+
+  it('throws a helpful error when neither layout has been built', () => {
+    expect(() => resolveWebRoot(root)).toThrow(/@zoon\/web.*build/i)
+  })
+})
+
+describe('webSourcePackage', () => {
+  it('returns the source package dir when sibling zoon/packages/web exists', () => {
+    const cliRoot = join(root, 'zooid', 'packages', 'cli')
+    mkdirSync(cliRoot, { recursive: true })
+    const webPkg = join(root, 'zoon', 'packages', 'web')
+    mkdirSync(webPkg, { recursive: true })
+    writeFileSync(join(webPkg, 'package.json'), '{"name":"@zoon/web"}')
+    expect(webSourcePackage(cliRoot)).toBe(webPkg)
+  })
+
+  it('returns null outside the monorepo', () => {
+    expect(webSourcePackage(root)).toBeNull()
+  })
+})

package/src/web/resolve.ts

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+const ENV_OVERRIDE = 'ZOOID_DEV_WEB_ROOT_OVERRIDE'
+
+export function resolveWebRoot(cliRoot: string): string {
+  const override = process.env[ENV_OVERRIDE]
+  if (override && existsSync(join(override, 'index.html'))) return resolve(override)
+
+  const published = join(cliRoot, 'dist', 'web')
+  if (existsSync(join(published, 'index.html'))) return published
+
+  const fromSource = webSourcePackage(cliRoot)
+  if (fromSource && existsSync(join(fromSource, 'dist', 'index.html'))) {
+    return join(fromSource, 'dist')
+  }
+
+  throw new Error(
+    `@zoon/web build not found.\n  Tried: ${published}\n  Tried: ${fromSource ?? '(no monorepo source)'}\n` +
+      `Run \`pnpm -C zoon/packages/web build\` (or set ${ENV_OVERRIDE} to a built dist).`,
+  )
+}
+
+// Returns the path to the in-tree @zoon/web package (zoon/packages/web) if the
+// CLI is running from the monorepo source. Returns null when running from an
+// installed package (no sibling zoon/ tree).
+export function webSourcePackage(cliRoot: string): string | null {
+  const workspaceRoot = dirname(dirname(dirname(cliRoot)))
+  const candidate = join(workspaceRoot, 'zoon', 'packages', 'web')
+  return existsSync(join(candidate, 'package.json')) ? candidate : null
+}

package/src/web/static.test.ts

@@ -0,0 +1,51 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { webStatic } from './static.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-web-'))
+  mkdirSync(join(dir, 'assets'), { recursive: true })
+  writeFileSync(join(dir, 'index.html'), '<!doctype html><div id=root></div>')
+  writeFileSync(join(dir, 'assets', 'main.js'), 'console.log("ui")')
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('webStatic', () => {
+  it('serves index.html at /', async () => {
+    const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
+    const r = await app.request('/')
+    expect(r.status).toBe(200)
+    expect(await r.text()).toContain('id=root')
+  })
+
+  it('serves static assets', async () => {
+    const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
+    const r = await app.request('/assets/main.js')
+    expect(r.status).toBe(200)
+    expect(await r.text()).toContain('console.log("ui")')
+  })
+
+  it('synthesizes /config.json with the homeserver URL', async () => {
+    const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
+    const r = await app.request('/config.json')
+    expect(r.status).toBe(200)
+    expect(r.headers.get('content-type')).toMatch(/application\/json/)
+    expect(await r.json()).toEqual({ homeserver_url: 'http://localhost:8448' })
+  })
+
+  it('falls back to index.html for unknown routes (SPA history)', async () => {
+    const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
+    const r = await app.request('/room/!abc:localhost')
+    expect(r.status).toBe(200)
+    expect(await r.text()).toContain('id=root')
+  })
+
+  it('returns 404 for a missing asset', async () => {
+    const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
+    const r = await app.request('/assets/nope.js')
+    expect(r.status).toBe(404)
+  })
+})

package/src/web/static.ts

@@ -0,0 +1,61 @@
+import { readFileSync, statSync } from 'node:fs'
+import { extname, join, normalize } from 'node:path'
+import { Hono } from 'hono'
+
+export interface WebStaticOpts {
+  webRoot: string
+  homeserverUrl: string
+}
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+}
+
+function isAssetPath(p: string): boolean {
+  return p.startsWith('/assets/') || /\.[a-z0-9]+$/i.test(p)
+}
+
+export function webStatic(opts: WebStaticOpts): Hono {
+  const app = new Hono()
+
+  app.get('/config.json', (c) => c.json({ homeserver_url: opts.homeserverUrl }))
+
+  app.get('*', (c) => {
+    const url = new URL(c.req.url)
+    const requested = decodeURIComponent(url.pathname)
+    const wantFile = requested === '/' ? '/index.html' : requested
+
+    const safe = normalize(wantFile).replace(/^(\.\.[/\\])+/g, '')
+    const filePath = join(opts.webRoot, safe)
+    if (!filePath.startsWith(opts.webRoot)) return c.notFound()
+
+    try {
+      const stat = statSync(filePath)
+      if (stat.isFile()) {
+        const body = readFileSync(filePath)
+        const ct = MIME[extname(filePath)] ?? 'application/octet-stream'
+        return c.body(body as unknown as ArrayBuffer, 200, { 'content-type': ct })
+      }
+    } catch {
+      // fall through to history fallback
+    }
+
+    if (isAssetPath(requested)) return c.notFound()
+    const indexBytes = readFileSync(join(opts.webRoot, 'index.html'))
+    return c.body(indexBytes as unknown as ArrayBuffer, 200, {
+      'content-type': MIME['.html']!,
+    })
+  })
+
+  return app
+}

package/src/web/watch.ts

@@ -0,0 +1,103 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface WebWatchHandle {
+  distPath: string
+  // Pipe captured child output onwards. Call once Listr / interactive
+  // renderers are done, otherwise vite output will get garbled.
+  attachStdio: () => void
+  stop: () => Promise<void>
+}
+
+export interface WebWatchOpts {
+  webPackageDir: string
+  // Wait up to this many ms for vite's first build to finish before resolving.
+  firstBuildTimeoutMs?: number
+}
+
+// Spawns `vite build --watch` in webPackageDir and resolves once the first
+// build has completed (detected via index.html mtime > spawn time).
+export async function startWebWatch(opts: WebWatchOpts): Promise<WebWatchHandle> {
+  const distPath = join(opts.webPackageDir, 'dist')
+  const indexPath = join(distPath, 'index.html')
+  const timeoutMs = opts.firstBuildTimeoutMs ?? 60_000
+  const spawnTime = Date.now()
+
+  const child: ChildProcess = spawn(
+    'pnpm',
+    ['-C', opts.webPackageDir, 'exec', 'vite', 'build', '--watch'],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+
+  let buffered = ''
+  const onData = (chunk: Buffer): void => {
+    buffered += chunk.toString('utf8')
+  }
+  child.stdout?.on('data', onData)
+  child.stderr?.on('data', onData)
+
+  let attached = false
+  const attachStdio = (): void => {
+    if (attached) return
+    attached = true
+    child.stdout?.off('data', onData)
+    child.stderr?.off('data', onData)
+    if (buffered) process.stdout.write(buffered)
+    buffered = ''
+    child.stdout?.pipe(process.stdout)
+    child.stderr?.pipe(process.stderr)
+  }
+
+  let exited = false
+  child.once('exit', () => {
+    exited = true
+  })
+
+  while (Date.now() - spawnTime < timeoutMs) {
+    if (exited) {
+      attachStdio()
+      throw new Error(`vite build --watch exited before first build (code ${child.exitCode})`)
+    }
+    if (existsSync(indexPath)) {
+      const m = statSync(indexPath).mtimeMs
+      // Slack for clock granularity on macOS HFS+/APFS.
+      if (m >= spawnTime - 500) return makeHandle()
+    }
+    await new Promise((r) => setTimeout(r, 200))
+  }
+  // Timed out: clean up and surface what vite said.
+  attachStdio()
+  await stopChild(child)
+  throw new Error(`vite build --watch did not produce ${indexPath} within ${timeoutMs}ms`)
+
+  function makeHandle(): WebWatchHandle {
+    return {
+      distPath,
+      attachStdio,
+      stop: () => stopChild(child),
+    }
+  }
+}
+
+async function stopChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return
+  child.kill('SIGTERM')
+  await new Promise<void>((resolve) => {
+    let done = false
+    const finish = (): void => {
+      if (done) return
+      done = true
+      resolve()
+    }
+    child.once('exit', finish)
+    setTimeout(() => {
+      try {
+        child.kill('SIGKILL')
+      } catch {
+        // already gone
+      }
+      finish()
+    }, 2000)
+  })
+}