basango/AGENTS.md

Basango — AGENTS.md

Scope

• Applies to the entire repository.
• Use these conventions when adding/modifying code, scripts, or docs.

Environment

• Node: >= 22
• Package manager: Bun 1.3.x
• Task runner: Turborepo
• Lint/format: Biome

Workspace Layout

• workspaces: apps/* and packages/*.
• Internal packages use the @basango/ scope and workspace:* versions.
• Avoid nested packages like apps/** or packages/**.

Packages

• @basango/logger: Pino wrapper. Prefer named import import { logger } from "@basango/logger".
• @basango/db: Drizzle ORM for Postgres. Import via defined subpaths (./client, ./queries, ./schema, ./utils).
• @basango/ui: Shared UI.
• @basango/tsconfig: Shared TS configs. Extend this in apps/packages.

Conventions

• ESM-only: set "type": "module" for packages that ship code.
• TypeScript everywhere. Use extends: "@basango/tsconfig/base.json" when possible.
• Prefer named exports in libraries. Avoid barrel files unless necessary.
• Use workspace:* for internal dependencies; do not hardcode versions.
• Keep changes minimal and localized; avoid cross-cutting refactors without discussion.
• When using tRPC in React, always compose useQuery/useMutation from TanStack with trpc.*.queryOptions/mutationOptions instead of calling trpc.*.useQuery/useMutation helpers directly (they are deprecated).

Tasks & Commands

• Install: bun install (run at repo root only).
• Dev: bun run dev.
• Build: bun run build.
• Typecheck: bun run typecheck.
• Lint/format: bun run lint or bun run format.
• Turbo filtering examples:
  • bunx turbo dev --filter=@basango/crawler
  • bunx turbo build --filter=@basango/dashboard

Adding a New Package

• Place apps in apps/<name>; libraries in packages/<name>.
• Use scoped name: @basango/<name> and set "private": true unless publishing.
• If a lib exposes multiple entrypoints, prefer exports map over main.
• Add dependencies with bun add <pkg> in the package directory; internal deps as workspace:*.

Logging

• Import logger as import { logger } from "@basango/logger" for consistency.
• Production logs are structured JSON; non-production uses pino-pretty transport.

Testing

• Use vitest where present. Add tests locally to the package being changed.
• Keep tests fast and focused. Do not introduce global test state.

Quality Gates

• biome formatting/linting is enforced. Run before committing.
• manypkg check runs as part of bun run lint to validate workspace correctness.

Commits & Hooks

• Conventional commits via Commitizen: bunx cz.
• Commitlint enforces message format. Husky hooks run on commit.

Gotchas

• Ensure apps/* and packages/* are the only workspace globs.
• Prefer named import for logger to avoid mixing default/named across files.

Contact Points

• Architecture overview: docs/architecture.md.
• Forms handling patterns: docs/forms-handling.md.