zooid 0.6.1 → 0.7.0

package/src/commands/dev.ts

@@ -0,0 +1,308 @@
+import chalk from 'chalk'
+import { Listr } from 'listr2'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { serve, type ServerType } from '@hono/node-server'
+import {
+  findConfigFile,
+  findMatrixTransport,
+  loadZooidConfig,
+} from '@zooid/core'
+import { ensureAdminUser } from '../bootstrap/admin.js'
+import { writeBootstrapConfigs } from '../bootstrap/configs.js'
+import { resolveDataLayout } from '../bootstrap/data-layout.js'
+import { deriveHomeserverShape } from '../bootstrap/derive.js'
+import { resolvePaths } from '../bootstrap/paths.js'
+import { ensureTokens, type Tokens } from '../bootstrap/tokens.js'
+import { startDaemon, type DaemonHandle } from '../daemon/start-daemon.js'
+import { TuwunelService } from '../services/tuwunel.js'
+import { resolveWebRoot, webSourcePackage } from '../web/resolve.js'
+import { webStatic } from '../web/static.js'
+import { startWebWatch, type WebWatchHandle } from '../web/watch.js'
+import {
+  ensureDayFolder,
+  pruneOldDays,
+  resolveLogPaths,
+  type LogPaths,
+} from '../observability/paths.js'
+import {
+  wireAgentCapture,
+  type AgentCapture,
+} from '../observability/capture-agent.js'
+import { captureChildToFile } from '../observability/capture-tuwunel.js'
+import { buildShutdown } from './dev-cascade.js'
+
+// Walk up from this module until we find the @zooid/cli package.json. This
+// is robust to the source/bundle distinction: src/commands/dev.ts and
+// dist/bin.js end up at different depths, so a fixed `..` count breaks
+// after `tsup`. The package's "name" field disambiguates from any parent.
+const CLI_ROOT = (() => {
+  let dir = dirname(fileURLToPath(import.meta.url))
+  for (let i = 0; i < 8; i++) {
+    const pkgPath = resolve(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string }
+        if (pkg.name === 'zooid' || pkg.name === '@zooid/cli') return dir
+      } catch {
+        // ignore
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error('cli root not found (no @zooid/cli package.json above ' + import.meta.url + ')')
+})()
+
+export interface DevFlags {
+  cwd?: string
+  dataDir: string
+  hostPort?: number
+  uiPort: number
+  engine: 'docker' | 'podman'
+  adminUser: string
+  adminPassword: string
+  installSignalHandlers?: boolean
+  foreground?: boolean
+  // When true, run `vite build --watch` against the in-tree @zoon/web package
+  // and serve its dist directly. Requires running from the monorepo source.
+  watchWeb?: boolean
+}
+
+export interface DevHandle {
+  stop: () => Promise<void>
+}
+
+interface DevCtx {
+  tokens?: Tokens
+  svc?: TuwunelService
+  daemon?: DaemonHandle
+  uiServer?: ServerType
+  webWatch?: WebWatchHandle
+  logPaths?: LogPaths
+  captures?: Record<string, AgentCapture>
+  tuwunelCaptureDone?: Promise<void>
+}
+
+export async function runDev(flags: DevFlags): Promise<DevHandle> {
+  const cwd = flags.cwd ?? process.cwd()
+  const found = findConfigFile(cwd)
+  if (!found) throw new Error(`zooid.yaml not found in ${cwd}`)
+  // Load .env files from the workforce dir before anything reads process.env.
+  // Order matches the convention used by Vite/Next: .env.local overrides .env,
+  // and real shell vars override both (loadEnvFile never overwrites existing
+  // process.env entries). Spawned agents inherit these via runtime-local.
+  loadEnvFiles(cwd)
+
+  // Resolve data paths up front — they only depend on cwd/flags, not the
+  // parsed config — so we can ensure tokens before any loadZooidConfig call.
+  const dataRoot = resolve(cwd, flags.dataDir)
+  const layout = resolveDataLayout(dataRoot)
+  const paths = resolvePaths(layout.matrixDir)
+  const logPaths = resolveLogPaths({ dataDir: layout.dataRoot })
+
+  // Bootstrap AS tokens and export to env BEFORE parsing zooid.yaml. The
+  // parser's MATRIX_AS_TOKEN / MATRIX_HS_TOKEN defaults (see [ZOD048]) and
+  // any explicit `${MATRIX_AS_TOKEN}` interpolations both need the vars set.
+  const tokens = ensureTokens(paths.envPath)
+  process.env.MATRIX_AS_TOKEN = tokens.asToken
+  process.env.MATRIX_HS_TOKEN = tokens.hsToken
+
+  const rawYaml = readFileSync(found.path, 'utf8')
+  const preview = loadZooidConfig(rawYaml)
+  const matrix = findMatrixTransport(preview)
+  if (!matrix) {
+    throw new Error('zooid.yaml: zooid dev requires at least one matrix transport')
+  }
+  const agentUserIds = Object.values(preview.agents)
+    .filter((a) => a.matrix?.transport === matrix.name)
+    .map((a) => a.matrix!.user_id)
+  const shape = deriveHomeserverShape(matrix.transport, agentUserIds)
+  const port = flags.hostPort ?? shape.port
+  const homeserver = `http://localhost:${port}`
+
+  await ensureDayFolder(logPaths)
+  await pruneOldDays({ dataDir: layout.dataRoot, retainDays: 14 })
+
+  const ctx: DevCtx = { logPaths, tokens }
+
+  const tasks = new Listr<DevCtx>(
+    [
+      {
+        title: 'Write tuwunel.toml + appservice.yaml',
+        task: () => {
+          if (!ctx.tokens) throw new Error('tokens not ready')
+          writeBootstrapConfigs({
+            paths,
+            serverName: shape.serverName,
+            asToken: ctx.tokens.asToken,
+            hsToken: ctx.tokens.hsToken,
+            senderLocalpart: matrix.transport.sender_localpart,
+            userNamespace: matrix.transport.user_namespace,
+          })
+        },
+      },
+      {
+        title: `Start Tuwunel container (${flags.engine})`,
+        task: () => {
+          ctx.svc = new TuwunelService({
+            name: 'zooid-tuwunel',
+            hostPort: port,
+            paths,
+            engine: flags.engine,
+          })
+          const child = ctx.svc.start()
+          ctx.tuwunelCaptureDone = captureChildToFile(child, logPaths.tuwunelLog)
+        },
+      },
+      {
+        title: 'Wait for Tuwunel /_matrix/client/versions',
+        task: async () => {
+          if (!ctx.svc) throw new Error('service not started')
+          await ctx.svc.waitHealthy({ url: homeserver, timeoutMs: 60_000 })
+        },
+      },
+      {
+        title: `Register admin user @${flags.adminUser}:${shape.serverName}`,
+        task: async (_, t) => {
+          const r = await ensureAdminUser({
+            homeserver,
+            username: flags.adminUser,
+            password: flags.adminPassword,
+          })
+          t.title = r.created
+            ? `Registered admin: ${r.userId}`
+            : `Admin already exists: ${r.userId}`
+        },
+      },
+      {
+        title: 'Start daemon',
+        task: async () => {
+          const captures: Record<string, AgentCapture> = {}
+          for (const name of Object.keys(preview.agents)) {
+            captures[name] = wireAgentCapture({
+              agent: name,
+              paths: logPaths,
+              verbosity: 'default',
+              // Matrix cross-link is a follow-up — wire to transport-matrix's
+              // most-recent (room_id, event_id) per session in a later cycle.
+              matrixContext: () => null,
+            })
+          }
+          ctx.captures = captures
+          ctx.daemon = await startDaemon({
+            configPath: found.path,
+            cwd,
+            installSignalHandlers: false,
+            adminUserId: `@${flags.adminUser}:${shape.serverName}`,
+            agentsDir: layout.agentsDir,
+            onTap: (agentName, event) => captures[agentName]?.onTap(event),
+          })
+        },
+      },
+      ...(flags.watchWeb
+        ? [
+            {
+              title: 'Start @zoon/web watcher (vite build --watch)',
+              task: async (): Promise<void> => {
+                const pkgDir = webSourcePackage(CLI_ROOT)
+                if (!pkgDir) {
+                  throw new Error(
+                    '--watch-web requires running from the monorepo source (no zoon/packages/web found).',
+                  )
+                }
+                ctx.webWatch = await startWebWatch({ webPackageDir: pkgDir })
+              },
+            },
+          ]
+        : []),
+      {
+        title: `Serve @zoon/web on http://localhost:${flags.uiPort}`,
+        task: () => {
+          const webRoot = ctx.webWatch?.distPath ?? resolveWebRoot(CLI_ROOT)
+          const app = webStatic({ webRoot, homeserverUrl: homeserver })
+          ctx.uiServer = serve({ fetch: app.fetch, port: flags.uiPort })
+        },
+      },
+    ],
+    { concurrent: false, exitOnError: true },
+  )
+
+  await tasks.run()
+
+  // Listr's interactive renderer is done — start streaming the watcher's
+  // output to our terminal so vite rebuild logs are visible.
+  ctx.webWatch?.attachStdio()
+
+  const shutdown = buildShutdown({
+    stopUi: async () => {
+      const s = ctx.uiServer
+      if (!s) return
+      await new Promise<void>((r) => s.close(() => r()))
+    },
+    stopDaemon: async () => {
+      await ctx.daemon?.stop()
+    },
+    stopTuwunel: async () => {
+      await ctx.svc?.stop()
+    },
+    stopWebWatch: async () => {
+      await ctx.webWatch?.stop()
+    },
+    stopCaptures: async () => {
+      if (!ctx.captures) return
+      await Promise.all(Object.values(ctx.captures).map((c) => c.close()))
+    },
+    finalizeTuwunelCapture: async () => {
+      if (ctx.tuwunelCaptureDone) await ctx.tuwunelCaptureDone
+    },
+  })
+
+  if (flags.installSignalHandlers !== false) {
+    const handler = async (): Promise<void> => {
+      process.stdout.write(chalk.dim('\nStopping…\n'))
+      await shutdown()
+      process.exit(0)
+    }
+    process.on('SIGINT', () => void handler())
+    process.on('SIGTERM', () => void handler())
+  }
+
+  process.stdout.write(
+    [
+      '',
+      chalk.bold('Tuwunel is up.') + ` ${homeserver}`,
+      chalk.bold('UI:        ') + ` http://localhost:${flags.uiPort}`,
+      `  ${chalk.cyan('admin user:')} ${flags.adminUser} / ${flags.adminPassword}`,
+      `  ${chalk.cyan('data dir:')} ${layout.dataRoot}`,
+      ...(ctx.webWatch
+        ? [`  ${chalk.cyan('web watcher:')} live (vite build --watch on @zoon/web)`]
+        : []),
+      '',
+      chalk.dim('Press Ctrl-C to stop.'),
+      '',
+    ].join('\n'),
+  )
+
+  if (flags.foreground !== false) {
+    await ctx.daemon!.whenStopped
+  }
+
+  return { stop: shutdown }
+}
+
+function loadEnvFiles(cwd: string): void {
+  // .env.local takes precedence over .env, but neither overrides shell-exported
+  // vars — process.loadEnvFile() refuses to overwrite already-set keys.
+  for (const name of ['.env.local', '.env']) {
+    const path = resolve(cwd, name)
+    if (!existsSync(path)) continue
+    try {
+      process.loadEnvFile(path)
+    } catch (err) {
+      console.warn(`[zooid dev] failed to load ${name}: ${(err as Error).message}`)
+    }
+  }
+}

package/src/commands/init/generators.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import {
+  generateZooidYaml,
+  generateAgentsMd,
+  generateClaudeSettings,
+  generateOpencodeJson,
+  generateEnv,
+  generateGitignore,
+} from './generators.js'
+
+describe('generateZooidYaml', () => {
+  it('produces the short post-ZOD048 shape for claude + model', () => {
+    const out = generateZooidYaml({
+      preset: 'claude',
+      model: 'claude-sonnet-4-6',
+    })
+    expect(out).toContain('runtime: local')
+    expect(out).toContain('homeserver: http://localhost:8448')
+    expect(out).toContain('port: 9099')
+    expect(out).toContain('zooid-assistant:')
+    expect(out).toContain('preset: claude')
+    expect(out).toContain('model: claude-sonnet-4-6')
+    expect(out).toContain("display_name: 'Zooid Assistant'")
+    expect(out).toContain("rooms: ['#zooid']")
+    expect(out).not.toContain('user_id:')
+    expect(out).not.toContain('workdir:')
+    expect(out).not.toContain('transport: matrix')
+  })
+
+  it('omits model on the acp block for opencode (model lives in opencode.json)', () => {
+    const out = generateZooidYaml({ preset: 'opencode' })
+    expect(out).toContain('acp: { preset: opencode }')
+    expect(out).not.toContain('model:')
+  })
+})
+
+describe('generateClaudeMd', () => {
+  it('imports AGENTS.md via the @<path> directive Claude Code auto-loads', async () => {
+    const { generateClaudeMd } = await import('./generators.js')
+    expect(generateClaudeMd().trim()).toBe('@AGENTS.md')
+  })
+})
+
+describe('generateAgentsMd', () => {
+  it('names the assistant and points at the docs URL', () => {
+    const out = generateAgentsMd()
+    expect(out).toContain('zooid-assistant')
+    expect(out).toContain('https://zooid.dev/docs/')
+    expect(out).toContain('web fetch')
+  })
+})
+
+describe('generateClaudeSettings', () => {
+  it('emits a settings.json that allowlists WebFetch(domain:zooid.dev)', () => {
+    const out = generateClaudeSettings()
+    const parsed = JSON.parse(out)
+    expect(parsed.permissions.allow).toContain('WebFetch(domain:zooid.dev)')
+  })
+})
+
+describe('generateOpencodeJson', () => {
+  it('produces opencode-go/<model> with the OPENCODE_API_KEY env reference', () => {
+    const out = generateOpencodeJson({
+      provider: 'opencode-go',
+      model: 'kimi-k2.6',
+      apiKeyEnvVar: 'OPENCODE_API_KEY',
+    })
+    const parsed = JSON.parse(out)
+    expect(parsed.model).toBe('opencode-go/kimi-k2.6')
+    expect(parsed.provider['opencode-go'].options.apiKey).toBe('{env:OPENCODE_API_KEY}')
+    expect(parsed.permission.webfetch).toBe('allow')
+  })
+
+  it('produces a TODO stub for the custom provider', () => {
+    const out = generateOpencodeJson({ provider: 'custom' })
+    const parsed = JSON.parse(out)
+    expect(parsed.model).toMatch(/TODO/)
+    expect(parsed.provider).toHaveProperty('TODO')
+  })
+})
+
+describe('generateEnv', () => {
+  it('emits a single line with the right env var name', () => {
+    expect(generateEnv({ envVar: 'ANTHROPIC_API_KEY', value: 'sk-ant-x' })).toBe(
+      'ANTHROPIC_API_KEY=sk-ant-x\n',
+    )
+  })
+})
+
+describe('generateGitignore', () => {
+  it('ignores .env, node_modules, and data/', () => {
+    const out = generateGitignore()
+    expect(out).toContain('.env')
+    expect(out).toContain('node_modules/')
+    expect(out).toContain('data/')
+  })
+})

package/src/commands/init/generators.ts

@@ -0,0 +1,119 @@
+export interface ZooidYamlOpts {
+  preset: 'claude' | 'codex' | 'opencode'
+  /** Only set for claude / codex; opencode reads its own opencode.json. */
+  model?: string
+}
+
+export function generateZooidYaml(opts: ZooidYamlOpts): string {
+  const acpBlock =
+    opts.preset === 'opencode'
+      ? `    acp: { preset: opencode }`
+      : `    acp:\n      preset: ${opts.preset}\n      model: ${opts.model}`
+  return `runtime: local
+
+transports:
+  matrix:
+    homeserver: http://localhost:8448
+    port: 9099
+
+agents:
+  zooid-assistant:
+${acpBlock}
+    matrix:
+      display_name: 'Zooid Assistant'
+      rooms: ['#zooid']
+`
+}
+
+export function generateAgentsMd(): string {
+  return `# zooid-assistant
+
+You are the zooid setup assistant. Your job is to help the operator get a workforce running, add agents, and configure zooid for their use case.
+
+## Resources
+
+- Zooid documentation: https://zooid.dev/docs/
+- Use your web fetch tool to read documentation pages when answering questions.
+
+## Behavior
+
+- Be terse. Give the answer; link to the doc page; stop.
+- When the operator asks how to do something, prefer to fetch the relevant docs section over guessing from training data.
+- When the operator asks you to *configure* something, propose a yaml edit and let them apply it. Don't write files directly unless they ask.
+`
+}
+
+/**
+ * Claude Code auto-loads `CLAUDE.md`, not `AGENTS.md`. We keep `AGENTS.md`
+ * as the canonical content (codex / opencode read it directly) and ship a
+ * one-line `CLAUDE.md` that pulls it in via Claude Code's `@<path>` import.
+ */
+export function generateClaudeMd(): string {
+  return `@AGENTS.md\n`
+}
+
+export function generateClaudeSettings(): string {
+  return (
+    JSON.stringify(
+      {
+        permissions: {
+          allow: ['WebFetch(domain:zooid.dev)'],
+        },
+      },
+      null,
+      2,
+    ) + '\n'
+  )
+}
+
+export interface OpencodeJsonOpts {
+  provider: string
+  model?: string
+  apiKeyEnvVar?: string
+}
+
+export function generateOpencodeJson(opts: OpencodeJsonOpts): string {
+  if (opts.provider === 'custom') {
+    return (
+      JSON.stringify(
+        {
+          $schema: 'https://opencode.ai/config.json',
+          model: 'TODO/your-model',
+          provider: { TODO: { options: {} } },
+        },
+        null,
+        2,
+      ) + '\n'
+    )
+  }
+  const cfg = {
+    $schema: 'https://opencode.ai/config.json',
+    model: `${opts.provider}/${opts.model}`,
+    provider: {
+      [opts.provider]: {
+        options: { apiKey: `{env:${opts.apiKeyEnvVar}}` },
+      },
+    },
+    permission: { webfetch: 'allow' as const },
+  }
+  return JSON.stringify(cfg, null, 2) + '\n'
+}
+
+export interface EnvOpts {
+  envVar: string
+  value: string
+}
+
+export function generateEnv(opts: EnvOpts): string {
+  return `${opts.envVar}=${opts.value}\n`
+}
+
+export function generateGitignore(): string {
+  return ['.env', 'node_modules/', 'data/', ''].join('\n')
+}
+
+export function generateOpencodeReadme(): string {
+  return `See https://opencode.ai/config for the full opencode.json schema, including
+provider-specific options and per-tool permissions.
+`
+}

package/src/commands/init/prompts.ts

@@ -0,0 +1,123 @@
+import { select, password } from '@inquirer/prompts'
+import {
+  OPENCODE_PROVIDERS,
+  findOpencodeProvider,
+  findSimplePreset,
+} from './registry.js'
+import type { InitOptions } from '../init.js'
+
+export interface PromptInput {
+  dir: string
+  preset?: string
+  auth?: string
+  model?: string
+  provider?: string
+  apiKey?: string
+  force?: boolean
+  overwrite?: boolean
+  interactive?: boolean
+}
+
+export async function resolveOptions(flags: PromptInput): Promise<InitOptions> {
+  const interactive = flags.interactive !== false && Boolean(process.stdin.isTTY)
+  const ask = <T>(prompt: () => Promise<T>, fallback: () => string): Promise<T> => {
+    if (!interactive) return Promise.reject(new Error(fallback()))
+    return prompt()
+  }
+
+  const preset = (flags.preset as InitOptions['preset']) ?? (await ask(
+    () => select({
+      message: 'Which agent should zooid-assistant use?',
+      choices: [
+        { name: 'claude (Claude Code)', value: 'claude' as const },
+        { name: 'codex (OpenAI Codex)', value: 'codex' as const },
+        { name: 'opencode', value: 'opencode' as const },
+      ],
+    }),
+    () => '--preset is required (claude | codex | opencode)',
+  ))
+
+  if (preset === 'opencode') {
+    const provider = flags.provider ?? (await ask(
+      () => select({
+        message: 'Which provider?',
+        choices: [
+          ...OPENCODE_PROVIDERS.map((p) => ({
+            name: `${p.label}  (${p.description})`,
+            value: p.id,
+          })),
+          { name: 'custom (write your own opencode.json block)', value: 'custom' },
+        ],
+      }),
+      () => '--provider is required for opencode',
+    ))
+    if (provider === 'custom') {
+      return {
+        dir: flags.dir,
+        preset,
+        provider,
+        force: flags.force,
+        overwrite: flags.overwrite,
+      }
+    }
+    const meta = findOpencodeProvider(provider)
+    if (!meta) throw new Error(`unknown opencode provider: ${provider}`)
+    const model = flags.model ?? (await ask(
+      () => select({
+        message: 'Which model?',
+        choices: meta.models.map((m) => ({ name: m, value: m })),
+      }),
+      () => '--model is required',
+    ))
+    const apiKey = flags.apiKey ?? (await ask(
+      () => password({ message: `${meta.label} API key:` }),
+      () => '--api-key is required',
+    ))
+    return {
+      dir: flags.dir,
+      preset,
+      provider,
+      model,
+      apiKey,
+      force: flags.force,
+      overwrite: flags.overwrite,
+    }
+  }
+
+  const meta = findSimplePreset(preset)
+  if (!meta) throw new Error(`unknown preset: ${preset}`)
+  const auth = (flags.auth as 'subscription' | 'api-key') ?? (await ask(
+    () => select({
+      message: 'How do you authenticate?',
+      choices: [
+        { name: `My ${meta.subscriptionLabel}`, value: 'subscription' as const },
+        { name: `I'll provide an API key`, value: 'api-key' as const },
+      ],
+    }),
+    () => '--auth is required (subscription | api-key)',
+  ))
+  const model = flags.model ?? (await ask(
+    () => select({
+      message: 'Which model?',
+      choices: meta.models.map((m) => ({ name: m, value: m })),
+    }),
+    () => '--model is required',
+  ))
+  const apiKey =
+    auth === 'api-key'
+      ? flags.apiKey ?? (await ask(
+          () => password({ message: `${meta.apiKeyPromptLabel} API key:` }),
+          () => '--api-key is required when --auth=api-key',
+        ))
+      : undefined
+
+  return {
+    dir: flags.dir,
+    preset,
+    auth,
+    model,
+    apiKey,
+    force: flags.force,
+    overwrite: flags.overwrite,
+  }
+}

package/src/commands/init/registry.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import {
+  SIMPLE_PRESETS,
+  OPENCODE_PROVIDERS,
+  findSimplePreset,
+  findOpencodeProvider,
+} from './registry.js'
+
+describe('init registry', () => {
+  it('SIMPLE_PRESETS contains claude and codex with non-empty model lists', () => {
+    const names = SIMPLE_PRESETS.map((p) => p.preset)
+    expect(names).toEqual(['claude', 'codex'])
+    for (const p of SIMPLE_PRESETS) {
+      expect(p.models.length).toBeGreaterThan(0)
+      expect(p.apiKeyEnvVar).toMatch(/^[A-Z_]+_API_KEY$/)
+      expect(p.credentialDir.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('OPENCODE_PROVIDERS lists opencode-go first as the recommended default', () => {
+    expect(OPENCODE_PROVIDERS[0]?.id).toBe('opencode-go')
+  })
+
+  it('findSimplePreset returns the entry by name', () => {
+    expect(findSimplePreset('claude')?.preset).toBe('claude')
+    expect(findSimplePreset('nope')).toBeUndefined()
+  })
+
+  it('findOpencodeProvider returns the entry by id', () => {
+    expect(findOpencodeProvider('opencode-go')?.id).toBe('opencode-go')
+    expect(findOpencodeProvider('nope')).toBeUndefined()
+  })
+})