Initial commit: restructure to flat layout with ui/ and web/ at root

2026-03-12 21:33:50 +08:00
commit decba25a08
1708 changed files with 199890 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,128 @@
+# OpenChamber - AI Agent Reference (verified)
+
+## Core purpose
+OpenChamber is a web-based UI runtime for interacting with an OpenCode server (local auto-start or remote URL). UI uses HTTP + SSE via `@opencode-ai/sdk`.
+
+## Tech stack (source of truth: `package.json`, resolved: `bun.lock`)
+- Runtime/tooling: Bun (`package.json` `packageManager`), Node >=20 (`package.json` `engines`)
+- UI: React, TypeScript, Vite, Tailwind v4
+- State: Zustand (`ui/src/stores/`)
+- UI primitives: Radix UI (`package.json` deps), HeroUI (`package.json` deps), Remixicon (`package.json` deps)
+- Server: Express (`web/server/index.js`)
+
+## Monorepo layout
+No longer using workspaces (see `package.json`).
+- Shared UI: `ui`
+- Web app + server + CLI: `web`
+
+## Documentation map
+Before changing any mapped module, read its module documentation first.
+
+### web
+Web runtime and server implementation for OpenChamber.
+
+#### lib
+Server-side integration modules used by API routes and runtime services.
+
+##### quota
+Quota provider registry, dispatch, and provider integrations for usage endpoints.
+- Module docs: `web/server/lib/quota/DOCUMENTATION.md`
+
+##### git
+Git repository operations for the web server runtime.
+- Module docs: `web/server/lib/git/DOCUMENTATION.md`
+
+##### github
+GitHub authentication, OAuth device flow, Octokit client factory, and repository URL parsing.
+- Module docs: `web/server/lib/github/DOCUMENTATION.md`
+
+##### opencode
+OpenCode server integration utilities including config management, provider authentication, and UI authentication.
+- Module docs: `web/server/lib/opencode/DOCUMENTATION.md`
+
+##### notifications
+Notification message preparation utilities for system notifications, including text truncation and optional summarization.
+- Module docs: `web/server/lib/notifications/DOCUMENTATION.md`
+
+##### terminal
+WebSocket protocol utilities for terminal input handling including message normalization, control frame parsing, and rate limiting.
+- Module docs: `web/server/lib/terminal/DOCUMENTATION.md`
+
+##### tts
+Server-side text-to-speech services and summarization helpers for `/api/tts/*` endpoints.
+- Module docs: `web/server/lib/tts/DOCUMENTATION.md`
+
+##### skills-catalog
+Skills catalog management including discovery, installation, and configuration of agent skill packages.
+- Module docs: `web/server/lib/skills-catalog/DOCUMENTATION.md`
+
+## Build / dev commands (verified)
+All scripts are in `package.json`.
+- Validate: `bun run type-check:web`, `bun run lint:web` (or use :ui variants)
+- Build: `bun run build:web` and/or `bun run build:ui`
+- Package for distribution: `bun run package` (outputs to `dist-output/`)
+
+## Distribution
+Run `bun run package` to generate `dist-output/` folder for distribution.
+Users then run:
+```bash
+cd dist-output
+npm install --omit=dev
+npm run start
+```
+
+## Runtime entry points
+- Web bootstrap: `web/src/main.tsx`
+- Web server: `web/server/index.js`
+- Web CLI: `web/bin/cli.js` (package bin: `web/package.json`)
+
+## OpenCode integration
+- UI client wrapper: `ui/src/lib/opencode/client.ts` (imports `@opencode-ai/sdk/v2`)
+- SSE hookup: `ui/src/hooks/useEventStream.ts`
+- Web server embeds/starts OpenCode server: `web/server/index.js` (`createOpencodeServer`)
+- Web runtime filesystem endpoints: search `web/server/index.js` for `/api/fs/`
+- External server support: Set `OPENCODE_HOST` (full base URL, e.g. `http://hostname:4096`) or `OPENCODE_PORT`, plus `OPENCODE_SKIP_START=true`, to connect to existing OpenCode instance
+
+## Key UI patterns (reference files)
+- Settings shell: `ui/src/components/views/SettingsView.tsx`
+- Settings shared primitives: `ui/src/components/sections/shared/`
+- Settings sections: `ui/src/components/sections/` (incl `skills/`)
+- Chat UI: `ui/src/components/chat/` and `ui/src/components/chat/message/`
+- Theme + typography: `ui/src/lib/theme/`, `ui/src/lib/typography.ts`
+- Terminal UI: `ui/src/components/terminal/` (uses `ghostty-web`)
+
+## External / system integrations (active)
+- Git: `ui/src/lib/gitApi.ts`, `web/server/index.js` (`simple-git`)
+- Terminal PTY: `web/server/index.js` (`bun-pty`/`node-pty`)
+- Skills catalog: `web/server/lib/skills-catalog/`, UI: `ui/src/components/sections/skills/`
+
+## Agent constraints
+- Do not modify `../opencode` (separate repo).
+- Do not run git/GitHub commands unless explicitly asked.
+- Keep baseline green (run `bun run type-check:web`, `bun run lint:web`, `bun run build:web` before finalizing changes).
+
+## Development rules
+- Keep diffs tight; avoid drive-by refactors.
+- Follow local precedent; search nearby code first.
+- TypeScript: avoid `any`/blind casts; keep ESLint/TS green.
+- React: prefer function components + hooks; class only when needed (e.g. error boundaries).
+- Control flow: avoid nested ternaries; prefer early returns + `if/else`/`switch`.
+- Styling: Tailwind v4; typography via `ui/src/lib/typography.ts`; theme vars via `ui/src/lib/theme/`.
+- Toasts: use custom toast wrapper from `@/components/ui` (backed by `ui/src/components/ui/toast.ts`); do not import `sonner` directly in feature code.
+- No new deps unless asked.
+- Never add secrets (`.env`, keys) or log sensitive data.
+
+## Theme System (MANDATORY for UI work)
+
+When working on any UI components, styling, or visual changes, agents **MUST** study the theme system skill first.
+
+**Before starting any UI work:**
+```
+skill({ name: "theme-system" })
+```
+
+This skill contains all color tokens, semantic logic, decision tree, and usage patterns. All UI colors must use theme tokens - never hardcoded values or Tailwind color classes.
+
+## Recent changes
+- Releases + high-level changes: `CHANGELOG.md`
+- Recent commits: `git log --oneline` (latest tags: `v1.8.x`)