codebay: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A web UI for spinning up isolated devcontainer instances from any local folder or Git repo URL, each exposing a browser-based VS Code (code-server). Pick a source → the app copies the folder (or clones the repo), injects code-server into its devcontainer.json, runs devcontainer up, and publishes the editor on a unique host port.

Runtime & commands

This runs on Bun only (Node.js is not supported). The app is built on Mochi, an SSR Svelte 5 framework with islands-based selective hydration, installed from npm as mochi-framework.

bun run dev        # dev server (MODE=development, project-local DATA_DIR, no browser launch)
bun run start      # runs src/index.ts directly (no separate build step needed)
bun run build      # mochi-framework build → .mochi/
bun run typecheck  # svelte-check (with a custom warning-ignore flag) + tsc --noEmit; run after any TS/Svelte change
bun test           # all tests
bun test src/index.isolated.test.ts          # single file
bun test -t "renders Hello world"            # single test by name
bun run checks     # format + eslint + typecheck + tests — run this after every change (see below)
bun run clean      # remove .mochi build output
bun run lint       # prettier --check + eslint (read-only; `checks` runs format instead of prettier --check, but the same eslint)
bun run gen:chimes # re-render attention chimes to public/sounds/ WAVs (after editing scripts/gen-chimes.ts)
bun run prod       # build + serve the production bundle
bun run verify:package # pack the tarball, install + boot it elsewhere (see npm packaging below)

Always run bun run checks after implementing a change (it runs format, then eslint, then typecheck, then test) and fix anything it surfaces before considering the work done.

Docker availability & testing strategy. The automated suite (bun test / bun run checks) is fully self-contained — even docker.isolated.test.ts stubs dockerode via globalThis.__codebayDocker, so no Docker daemon is required and the checks always run even where no daemon exists. Only end-to-end verification of the instance lifecycle — actually creating an instance, devcontainer up, the boot/health flow — needs a live daemon. Before attempting any such live verification, probe with docker info (or docker context inspect): if it's unavailable, don't try to boot instances — say so and fall back to the unit/isolated tests, which cover the orchestration logic against stubs. When Docker is running, live-boot verification becomes an option on top of the suite. The repo's own .devcontainer/ runs a nested daemon (docker-in-docker) rather than mounting the host's socket, because instances booted from inside it publish into that container's network namespace — the only place the proxy and the health probes look.