mirror of
https://github.com/usememos/memos.git
synced 2026-11-19 10:29:11 +01:00
fa2dcf59d5
Co-authored-by: johnnyjoygh <johnnyjoygg@gmail.com>
158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
# AGENTS.md
|
|
|
|
Repository instructions for AI coding agents. Keep this file short, concrete, and tied to commands that actually work in this
|
|
repo. If a fact here conflicts with source files or CI config, trust the source file and update this guide.
|
|
|
|
## Project Snapshot
|
|
|
|
Memos is a self-hosted note-taking app.
|
|
|
|
- Backend: Go 1.27.2, Echo v5, Connect RPC, gRPC-Gateway, Protocol Buffers.
|
|
- Frontend: React 19, TypeScript 7, Vite 8, Tailwind CSS v4, React Query v5.
|
|
- Storage: SQLite, MySQL, PostgreSQL.
|
|
- Generated API outputs: `proto/gen/` for Go/OpenAPI, `web/src/types/proto/` for TypeScript.
|
|
|
|
## Working Rules
|
|
|
|
- Read relevant code before editing; prefer local patterns over new abstractions.
|
|
- Keep diffs scoped. Do not do repo-wide cleanup, dependency churn, or generated-file rewrites unless the task requires it.
|
|
- Do not hand-edit generated proto outputs. Change `.proto` files, then run `buf generate`.
|
|
- Add migrations for all database drivers when schema changes, and update each driver's `LATEST.sql`.
|
|
- Add public API endpoints to `server/api/acl_config.go`.
|
|
- Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.
|
|
|
|
## Documentation
|
|
|
|
- ADRs and their companion glossary have been retired. Do not recreate them unless explicitly requested.
|
|
- Design documents in `docs/design/` are frozen after implementation. Do not update implemented designs to track later code changes.
|
|
- New and unimplemented designs may still evolve. Frozen documents record the original design; verify current behavior in source code and tests.
|
|
- Brand copy (tagline, descriptions, README intro) comes verbatim from [`BRAND.md`](https://github.com/usememos/.github/blob/main/BRAND.md) in `usememos/.github`. Change it there first; do not keep brand guidelines in this repo.
|
|
- Keep contributor guidance in this file and package-local `README.md` or `doc.go` files current when relevant code changes.
|
|
|
|
## Commands
|
|
|
|
Run from the repository root unless a command starts with `cd`.
|
|
|
|
```bash
|
|
# Backend
|
|
go run -buildvcs=true ./cmd/memos --port 8081 # Start backend with commit-derived CalVer
|
|
go test ./... # Run all Go tests
|
|
go test -v ./store/... # Store tests, including DB drivers via TestContainers
|
|
go test -v -race ./server/... # Server tests with race detector
|
|
go test -v -race ./internal/... # Internal package tests with race detector
|
|
go test -v -run TestFoo ./core/... # Run matching Go tests in one tree
|
|
go mod tidy -go=1.27.2 # Match CI tidy check
|
|
go fix ./... # Apply Go modernization fixes
|
|
go fix -diff ./... # Match CI modernization check
|
|
golangci-lint run # Go lint, config: .golangci.yaml (includes depguard layering rules)
|
|
golangci-lint run --fix # Auto-fix lint, including goimports
|
|
|
|
# Frontend
|
|
cd web && pnpm install # Install dependencies
|
|
cd web && pnpm dev # Dev server on :3001, proxying API to :8081
|
|
cd web && pnpm lint # Type check + Biome lint
|
|
cd web && pnpm test # Vitest unit tests
|
|
cd web && pnpm build # Production build
|
|
cd web && pnpm release # Build SPA into server/frontend/dist
|
|
|
|
# Protocol Buffers
|
|
cd proto && buf generate # Regenerate Go + TypeScript + OpenAPI
|
|
cd proto && buf lint # Lint proto files
|
|
cd proto && buf format -w # Format proto files
|
|
```
|
|
|
|
## Repository Layout
|
|
|
|
Every root folder is named for what it holds. Read the folder's `doc.go` or `README.md` before adding to it.
|
|
|
|
| Path | Holds | May import |
|
|
| --- | --- | --- |
|
|
| `cmd/memos/` | Cobra/Viper CLI setup and server startup | anything |
|
|
| `server/` | The HTTP process: Echo bootstrap, graceful shutdown, every transport | core, store, provider, markdown, filter, internal |
|
|
| `server/api/` | Connect/gRPC-Gateway services, ACL config, SSE hub. Thin handlers; rules go to `core/` | |
|
|
| `server/fileserver/` | Native HTTP file serving, thumbnails, range requests | |
|
|
| `server/frontend/` | Static SPA serving; `dist/` is the built SPA baked in by `go:embed` | |
|
|
| `server/mcp/` | Model Context Protocol server | |
|
|
| `server/auth/` | JWT access tokens, refresh tokens, PAT handling | |
|
|
| `core/` | Business rules with no HTTP and no SQL: `access`, `notification`, `memopayload`, `memoexport` | store, provider, markdown, filter, internal |
|
|
| `store/` | Store facade, cache, migrations, `Driver` interface; `store/db/{sqlite,mysql,postgres}/` implement it | provider, markdown, filter, internal |
|
|
| `markdown/` | Markdown engine: parser, AST, memos syntax extensions, renderer, memo payload | proto/gen, internal |
|
|
| `filter/` | CEL filter compiler: parse to IR, render to SQL per driver, filterable field schema | internal |
|
|
| `provider/` | Backends configured by instance settings: `ai`, `idp`, `storage` | proto/gen, internal |
|
|
| `internal/` | Private plumbing with no memos vocabulary (`identifier`, `email`, `webhook`, `ratelimit`, …) | third party only |
|
|
| `proto/api/`, `proto/store/` | Public API and internal storage proto sources; `proto/gen/` is generated | |
|
|
| `web/src/` | React SPA: `connect.ts` clients, `auth-state.ts`, `hooks/`, `contexts/`, `components/`, `themes/` | |
|
|
|
|
Layering rules, enforced by `depguard` in `.golangci.yaml`:
|
|
|
|
- Imports point downward only: `cmd` → `server` → `core` → `store` → {`provider`, `markdown`, `filter`} → `internal`.
|
|
- `internal/` packages import nothing from this module (except `internal/testutil`, which may import `proto/gen`).
|
|
- A package goes in `internal/` only if it could be published as a standalone module unchanged. If it knows what a Memo, Space, or instance setting is, it is a root package.
|
|
- Never create `util`, `common`, `base`, `helpers`, `misc`, or `pkg` packages. Name a package for the one thing it does, or put the code next to its only caller.
|
|
- New business rules extracted from `server/api` go to `core/<resource>/`, one package per resource.
|
|
|
|
File convention inside `server/api/`: `<resource>_service.go` holds the RPC handlers, `<resource>_service_converters.go` the
|
|
store↔proto conversion, and `<resource>_service_<topic>.go` further splits. Extend the matching file; do not add `*_helpers2.go`.
|
|
Black-box service tests live in `server/api/test/`, unit tests next to the code.
|
|
|
|
## Change Routing
|
|
|
|
| Change | Update | Verify |
|
|
| --- | --- | --- |
|
|
| Go service or router behavior | Handlers under `server/`, rules under `core/`, tests near package | `go test -v -race ./server/... ./core/...` |
|
|
| Store or migration behavior | `store/`, all three DB driver migrations, `LATEST.sql` | `go test -v ./store/...` |
|
|
| Markdown, filter, or provider logic | `markdown/`, `filter/`, `provider/` | `go test -v -race ./markdown/... ./filter/... ./provider/...` |
|
|
| Internal package logic | Relevant `internal/` package tests | `go test -v -race ./internal/...` |
|
|
| Frontend behavior | Components/hooks/contexts under `web/src/` | `cd web && pnpm lint && pnpm test` |
|
|
| Frontend production output | Vite config or release-sensitive UI | `cd web && pnpm build` or `pnpm release` |
|
|
| Proto API | `.proto` source, generated outputs, `proto/api/CHANGELOG.md` for breaks | `cd proto && buf generate && buf lint` |
|
|
| Public unauthenticated route | `server/api/acl_config.go` | Targeted server test or manual route check |
|
|
|
|
## Go Conventions
|
|
|
|
- Wrap errors with `errors.Wrap(err, "context")` from `github.com/pkg/errors`; do not use `fmt.Errorf`.
|
|
- Return service errors with `status.Errorf(codes.X, "message")`.
|
|
- Keep imports grouped as stdlib, third-party, then `github.com/usememos/memos`; goimports is run by golangci-lint.
|
|
- Add doc comments for exported identifiers; godot enforces exported comment punctuation.
|
|
- Avoid package-level mutable state unless the surrounding package already uses that pattern.
|
|
|
|
## Frontend Conventions
|
|
|
|
- Use `@/` for absolute imports.
|
|
- Follow Biome formatting: 2-space indent, double quotes, semicolons, 140-character line width.
|
|
- Put server data in React Query hooks under `web/src/hooks/`; keep UI-only state in contexts or component state.
|
|
- Use Tailwind CSS v4 utilities, `cn()` for class merging, and CVA for variants.
|
|
- Reuse Base UI primitives and existing components before adding new UI primitives.
|
|
- Keep generated proto TypeScript under `web/src/types/proto/` out of manual edits and Biome rewrites.
|
|
|
|
## Database And Proto Rules
|
|
|
|
- Schema changes require SQLite, MySQL, and PostgreSQL migrations plus `LATEST.sql` updates.
|
|
- Fresh-install SQL and incremental migrations must stay equivalent.
|
|
- Proto field changes must preserve compatibility unless the task explicitly allows a breaking API change. Record every
|
|
allowed break in `proto/api/CHANGELOG.md`; CI fails a `buf breaking` failure without an edit there.
|
|
- Regenerate after proto edits and include both Go/OpenAPI and TypeScript generated outputs.
|
|
|
|
## Verification Policy
|
|
|
|
- Run the narrowest relevant checks while iterating.
|
|
- Before finishing, run the checks that match the changed surface from "Change Routing".
|
|
- For docs-only changes, `git diff --check` is sufficient unless the docs include runnable examples that should be tested.
|
|
- If a required check cannot run locally, report the reason and the exact command that remains.
|
|
|
|
## CI Reference
|
|
|
|
- Releases are cut by pushing a `YY.MM[.N][-rc.N]` tag. To cut, promote, or check a release, follow
|
|
`.agents/skills/release/SKILL.md`.
|
|
- Development builds use the HEAD committer date in UTC as `YY.MM`; release builds inject the CalVer tag.
|
|
- `go build` embeds Git metadata automatically; `go run` needs `-buildvcs=true`. Builds without Git metadata must inject
|
|
`github.com/usememos/memos/internal/version.Version` through `-ldflags`.
|
|
- Docker excludes `.git`; pass `--build-arg VERSION="$(bash scripts/release_version.sh development-version)"` and
|
|
`--build-arg COMMIT="$(git rev-parse HEAD)"` when building locally (build frontend assets first).
|
|
|
|
- Backend CI: Go 1.27.2, `go mod tidy -go=1.27.2`, `go fix -diff ./...`, golangci-lint v2.14.0 (including goimports), test groups
|
|
`store`, `server`, `internal`, `other` (`cmd`, `core`, `markdown`, `filter`, `provider`, `proto`).
|
|
- Frontend CI: Node 24, pnpm 11.0.1, `pnpm lint`, `pnpm test`, `pnpm build`.
|
|
- Proto CI: `buf lint` and `buf format` check.
|
|
- Docker: `scripts/Dockerfile`, Alpine 3.21 runtime, non-root user, port 5230, multi-arch amd64/arm64/arm/v7.
|