58 lines
1.9 KiB
Markdown
58 lines
1.9 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure
|
|
|
|
This is an experimental TJWater Agent service. Runtime TypeScript lives in
|
|
`src/`; opencode agent assets live in `.opencode/`; tests live in `tests/`.
|
|
The project intentionally has no `cli/` directory and no user-auth middleware.
|
|
|
|
Key boundaries:
|
|
|
|
- `src/context/` owns local request context.
|
|
- `src/uiEnvelope/` owns the `agent-ui@1` protocol, registry, and tool mapping.
|
|
- `src/routes/` owns HTTP/SSE wiring.
|
|
- `src/results/`, `src/sessions/`, `src/memory/`, and `src/learning/` keep their existing persistence responsibilities.
|
|
|
|
Generated `data/`, `logs/`, and dependency folders must not be committed.
|
|
|
|
## Commands
|
|
|
|
Use Bun:
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
bun run check
|
|
bun test tests/**/*.test.ts
|
|
```
|
|
|
|
`bun run dev` starts `src/server.ts` in watch mode. `bun run check` runs
|
|
TypeScript checks for the main project and `.opencode`.
|
|
|
|
## Coding Notes
|
|
|
|
Use TypeScript ESM and keep types explicit at module boundaries. Preserve the
|
|
local service patterns before adding new abstractions. Do not reintroduce
|
|
free-form CLI command execution; future backend access should use typed tools or
|
|
adapters.
|
|
|
|
## Tests
|
|
|
|
Add focused Bun tests for route behavior, runtime/session state, result refs,
|
|
and UIEnvelope mapping. Tests must not depend on mutable files under `data/`.
|
|
|
|
## Security
|
|
|
|
This experimental service has no user authentication. Do not add secrets,
|
|
tokens, passwords, API keys, session dumps, or generated result references to
|
|
the repository. Keep `.env`, `data/`, and `logs/` statically denied in
|
|
`opencode.json`; do not replace those denials with prompt-only guidance. Keep
|
|
arbitrary Bash and edit operations approval-gated and subagents disabled.
|
|
|
|
## Runtime Readiness
|
|
|
|
Complete the OpenCode health check, warmup session, and model tool discovery
|
|
before the HTTP server starts listening. A warmup failure must fail startup.
|
|
Once listening, `/health` must expose the `ready` and `warmed_up` readiness
|
|
fields used by deployment checks.
|