From a2a693d9b4b7b3eba1b3b53f75ecd1ea8596fbca Mon Sep 17 00:00:00 2001 From: adhitShet <131381638+adhitShet@users.noreply.github.com> Date: Sat, 25 Apr 2026 10:15:40 +0530 Subject: [PATCH] docs: add AGENTS.md for AI agent guidance (#190) AGENTS.md is the declared agent-instruction source for this repo but has never been created. This adds it. Covers project structure (all internal packages), architectural facts (two-DB layout, FTS5 trigger-synced table, LOCK file, read-only mode, send retry, store path precedence), the full build gate including the CGO_CFLAGS workaround for GCC 15+ and the sqlite_fts5 tag requirement, coding style, testing guidelines, commit/PR conventions, and agent- specific notes (--read-only / WACLI_READONLY, --json output). All claims verified against source. Co-authored-by: Adi --- AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..042ddff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# Repository Guidelines + +## Project Structure +- `cmd/wacli/`: CLI command wiring (auth, sync, messages, send, media, contacts, chats, groups, history, presence, doctor). +- `internal/app/`: core app, whatsmeow event handling, backfill, sync idle logic. +- `internal/store/`: SQLite schema, migrations, FTS5 search, chats/contacts/groups/messages/media queries. +- `internal/wa/`: whatsmeow client wrapper, JID resolution, message parsing (text, business, media, context). +- `internal/config/`: store-dir resolution (`WACLI_STORE_DIR` env → XDG state dir on Linux → `~/.wacli`). +- `internal/lock/`: platform-specific LOCK-file locking; acquired before all write commands. +- `internal/out/`: JSON + table output helpers; all human text goes through here. +- `internal/fsutil/`: enforces 0700/0600 owner-only permissions on store files. +- `internal/pathutil/`: sanitises StorePath; rejects `?` and `#` to prevent URI injection. +- `internal/sqliteutil/`: sqlite file helpers. +- Tests sit next to the code they cover (`*_test.go`). + +## Key Architectural Facts +- **Two databases**: `session.db` (managed by whatsmeow) + `wacli.db` (app data, FTS5 search). +- **FTS5 table** is a separate trigger-synced table in `wacli.db`; requires `-tags sqlite_fts5` at build time. +- **Store lock**: a `LOCK` file in the store dir is acquired before any write operation; `--lock-wait` controls the wait timeout. +- **Read-only mode**: `--read-only` flag or `WACLI_READONLY=1` env; write commands exit immediately with a clear error. +- **Send retry**: bounded 45 s attempt timeout; retries once after reconnect for stale-session / usync-timeout errors. +- **Store path precedence**: `--store` flag → `WACLI_STORE_DIR` env → XDG `~/.local/state/wacli` on Linux (legacy `~/.wacli` fallback) → `~/.wacli` elsewhere. + +## Build, Test, and Development Commands +- Build: `pnpm build` — compiles with `-tags sqlite_fts5` and `CGO_CFLAGS=-Wno-error=missing-braces` (required for GCC 15+). +- Run: `pnpm wacli -- ` — rebuilds then runs. +- Test: `pnpm test` — runs `go test ./...` (plain), `go test -tags sqlite_fts5 ./...` (FTS), and a Windows lock cross-compile check. +- Lint: `pnpm lint` — `go vet ./...`. +- Format fix: `pnpm format` — `gofmt -w .`. +- Format check: `pnpm format:check` — fails if any file would change. +- **Full gate** (must pass before every PR): `pnpm format:check && pnpm lint && pnpm test && pnpm build && git diff --check`. + +## Coding Style +- Standard `gofmt` formatting; run `pnpm format` before committing. +- Output: send structured data to stdout (`--json` / table); send human hints, progress, and errors to stderr via `internal/out`. +- Prefer explicit error returns over panics; write short, early-return functions. +- No build-time CGO beyond sqlite3; keep the dependency tree minimal. + +## Testing Guidelines +- Every bug fix should ship with a regression test. +- FTS-sensitive tests must run under `-tags sqlite_fts5`; non-FTS path tests must also pass without the tag. +- Use `fake_wa_test.go` / table-driven tests for whatsmeow interaction; avoid hitting real WhatsApp in unit tests. +- Integration tests that need a live account are opt-in and not part of the standard gate. + +## Commit & Pull Request Guidelines +- Follow Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `security:`, `ci:` with an imperative summary. +- Keep commits focused; avoid bundling unrelated changes. +- PRs should state: what changed, why, how it was tested, and any new flags or env vars. +- Run the full gate locally before opening a PR; CI runs the same commands. +- New contributors: add `Co-authored-by:` trailers when building on their work. + +## Agent Notes +- This repo uses `AGENTS.md` as its agent-instruction source; `CLAUDE.md` is explicitly ignored. +- For agent-safe execution, pass `--read-only` (or set `WACLI_READONLY=1`) to prevent writes. +- Prefer `--json` output for machine-readable parsing. +- Do not add dependencies or change build tooling without confirming with the maintainer.