163 lines
5.3 KiB
Markdown
163 lines
5.3 KiB
Markdown
# OpenCode Monorepo Agent Guide
|
|
|
|
This file is for coding agents working in `/Users/ryanvogel/dev/opencode`.
|
|
|
|
## Scope And Precedence
|
|
|
|
- Start with this file for repo-wide defaults.
|
|
- Then check package-local `AGENTS.md` files for stricter rules.
|
|
- Existing local guides include `packages/opencode/AGENTS.md` and `packages/app/AGENTS.md`.
|
|
- Package-specific guides override this file when they conflict.
|
|
|
|
## Repo Facts
|
|
|
|
- Package manager: `bun` (`bun@1.3.11`).
|
|
- Monorepo tool: `turbo`.
|
|
- Default branch: `dev`.
|
|
- Root test script intentionally fails; do not run tests from root.
|
|
|
|
## Cursor / Copilot Rules
|
|
|
|
- No `.cursor/rules/` directory found.
|
|
- No `.cursorrules` file found.
|
|
- No `.github/copilot-instructions.md` file found.
|
|
- If these files are added later, treat them as mandatory project policy.
|
|
|
|
## High-Value Commands
|
|
|
|
Run commands from the correct package directory unless noted.
|
|
|
|
### Root
|
|
|
|
- Install deps: `bun install`
|
|
- Run all typechecks via turbo: `bun run typecheck`
|
|
- OpenCode dev CLI entry: `bun run dev`
|
|
- OpenCode serve (common): `bun run dev serve --hostname 0.0.0.0 --port 4096`
|
|
|
|
### `packages/opencode`
|
|
|
|
- Dev CLI: `bun run dev`
|
|
- Typecheck: `bun run typecheck`
|
|
- Tests (all): `bun test --timeout 30000`
|
|
- Tests (single file): `bun test test/path/to/file.test.ts --timeout 30000`
|
|
- Tests (single test name): `bun test test/path/to/file.test.ts -t "name fragment" --timeout 30000`
|
|
- Build: `bun run build`
|
|
- Drizzle helper: `bun run db`
|
|
|
|
### `packages/app`
|
|
|
|
- Dev server: `bun dev`
|
|
- Build: `bun run build`
|
|
- Typecheck: `bun run typecheck`
|
|
- Unit tests (all): `bun run test:unit`
|
|
- Unit tests (single file): `bun test --preload ./happydom.ts ./src/path/to/file.test.ts`
|
|
- Unit tests (single test name): `bun test --preload ./happydom.ts ./src/path/to/file.test.ts -t "name fragment"`
|
|
- E2E tests: `bun run test:e2e`
|
|
|
|
### `packages/mobile-voice`
|
|
|
|
- Start Expo: `bun run start`
|
|
- Start Expo dev client: `bunx expo start --dev-client --clear --host lan`
|
|
- iOS native run: `bun run ios`
|
|
- Android native run: `bun run android`
|
|
- Lint: `bun run lint`
|
|
- Expo doctor: `bunx expo-doctor`
|
|
- Dependency compatibility check: `bunx expo install --check`
|
|
|
|
### `packages/apn-relay`
|
|
|
|
- Start relay: `bun run dev`
|
|
- Typecheck: `bun run typecheck`
|
|
- DB connectivity check: `bun run db:check`
|
|
|
|
## Build / Lint / Test Expectations
|
|
|
|
- Always run the narrowest checks that prove your change.
|
|
- For backend changes: run package typecheck + relevant tests.
|
|
- For mobile changes: run `expo lint` and at least one `expo` compile-style command if possible.
|
|
- Never claim tests passed unless you ran them in this workspace.
|
|
|
|
## Single-Test Guidance
|
|
|
|
- Prefer running one file first, then broaden scope.
|
|
- For Bun tests, pass the file path directly.
|
|
- For name filtering, use `-t "..."`.
|
|
- Keep original timeouts when scripts define them.
|
|
|
|
## Code Style Guidelines
|
|
|
|
These conventions are already used heavily in this repo and should be preserved.
|
|
|
|
### Formatting
|
|
|
|
- Use Prettier defaults configured in root: `semi: false`, `printWidth: 120`.
|
|
- Keep imports grouped and stable; avoid noisy reorder-only edits.
|
|
- Avoid unrelated formatting churn in touched files.
|
|
|
|
### Imports
|
|
|
|
- Prefer explicit imports over dynamic imports unless runtime gating is required.
|
|
- Prefer existing alias patterns (for example `@/...`) where already configured.
|
|
- Do not introduce new dependency layers when a local util already exists.
|
|
|
|
### Types
|
|
|
|
- Avoid `any`.
|
|
- Prefer inference for local variables.
|
|
- Add explicit annotations for exported APIs and complex boundaries.
|
|
- Prefer `zod` schemas for request/response validation and parsing.
|
|
|
|
### Naming
|
|
|
|
- Follow existing repo preference for short, clear names.
|
|
- Use single-word names when readable; use multi-word only for clarity.
|
|
- Keep naming consistent with nearby code.
|
|
|
|
### Control Flow
|
|
|
|
- Prefer early returns over nested `else` blocks.
|
|
- Keep functions focused; split only when it improves reuse or readability.
|
|
|
|
### Error Handling
|
|
|
|
- Fail with actionable messages.
|
|
- Avoid swallowing errors silently.
|
|
- Log enough context to debug production issues (IDs, env, status), but never secrets.
|
|
- In UI code, degrade gracefully for missing capabilities.
|
|
|
|
### Data / DB
|
|
|
|
- For Drizzle schema, use snake_case fields and columns.
|
|
- Keep migration and schema changes minimal and explicit.
|
|
- Follow package-specific DB guidance in `packages/opencode/AGENTS.md`.
|
|
|
|
### Testing Philosophy
|
|
|
|
- Prefer testing real behavior over mocks.
|
|
- Add regression tests for bug fixes where practical.
|
|
- Keep fixtures small and focused.
|
|
|
|
## Agent Workflow Tips
|
|
|
|
- Read existing code paths before introducing new abstractions.
|
|
- Match local patterns first; do not impose a new style per file.
|
|
- If a package has its own `AGENTS.md`, review it before editing.
|
|
- For OpenCode Effect services, follow `packages/opencode/AGENTS.md` strictly.
|
|
|
|
## Known Operational Notes
|
|
|
|
- `packages/app/AGENTS.md` says: never restart app/server processes during that package's debugging workflow.
|
|
- `packages/app/AGENTS.md` also documents local backend+web split for UI work.
|
|
- `packages/opencode/AGENTS.md` contains mandatory Effect and database conventions.
|
|
|
|
## Regeneration / Special Scripts
|
|
|
|
- Regenerate JS SDK with: `./packages/sdk/js/script/build.ts`
|
|
|
|
## Quick Checklist Before Finishing
|
|
|
|
- Ran relevant package checks.
|
|
- Updated docs/config when behavior changed.
|
|
- Avoided committing unrelated files.
|
|
- Kept edits minimal and aligned with local conventions.
|