2.3 KiB
Repository Guidelines
Project Structure & Module Organization
This repository is the internal TJWater agent service. Runtime TypeScript code is organized under src/; CLI-specific code is under cli/src; Node test files live in node-tests/. Agent extensions and OpenCode integration files are under .opencode/, including .opencode/agents, .opencode/skills, and .opencode/tools. Runtime data, session metadata, logs, and result references are stored under data/ and logs/ and should be treated as local/generated state.
Deployment files are Dockerfile, docker-compose.yml, and .gitea/workflows/package.yml.
Build, Test, and Development Commands
Use Bun for this project:
bun install
bun run dev
bun run check
bun run test:cli
bun run start
bun run dev starts src/server.ts in watch mode. bun run check runs TypeScript checks for the main project and .opencode. bun run test:cli runs Node CLI tests. bun run start starts the service without watch mode.
Coding Style & Naming Conventions
Use TypeScript ESM and keep types explicit at module boundaries. Use two-space indentation, camelCase for functions and variables, PascalCase for classes/types, and kebab-case or descriptive lowercase names for scripts and data files. Prefer existing src/ service, route, and runtime patterns before introducing new structure.
Testing Guidelines
Tests use Node's built-in test runner for CLI coverage. Name test files with .node.mjs when using node --test, matching node-tests/cli/*.node.mjs. Add focused tests for CLI parsing, tool behavior, and session/runtime changes. Do not depend on mutable local files under data/.
Commit & Pull Request Guidelines
History uses Conventional Commit messages such as feat(tools): add search and map tools, fix(agent): warm up opencode on startup, and refactor(chat): .... Prefer feat(scope):, fix(scope):, or refactor(scope):.
PRs should describe runtime behavior changes, list bun run check and any test commands run, and mention changes to .opencode, secrets, ports, or deploy workflow behavior.
Security & Configuration Tips
Do not commit .env, logs, session transcripts, generated result references, or node_modules/. Keep registry and deploy credentials in Gitea secrets.