1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# AGENTS.md
  8
  9Guidance for AI coding agents working in this repository. Document only reflects what exists in code/docs.
 10
 11## Project Type
 12
 13- Language: Go
 14- CLI: Cobra executed via charmbracelet/fang
 15- Module path: `git.secluded.site/np`
 16- Binary name: `np`
 17
 18## Development Commands (Taskfile)
 19
 20- Format: `task fmt` (installs and runs gofumpt)
 21- Lint: `task lint` (golangci-lint)
 22- Static analysis: `task staticcheck`
 23- Tests: `task test` (go test -v ./...)
 24- Vulnerabilities: `task vuln` (govulncheck)
 25- License compliance: `task reuse` (REUSE)
 26- Build: `task build` (produces `./np`, injects version via ldflags)
 27- Run: `task run -- <flags>` (runs with ldflags)
 28- Docs: `task docs` (generates CLI docs via internal/tools/docgen)
 29- Pack: `task pack` (UPX compresses `np`)
 30- Clean: `task clean` / `task clean-all`
 31- Release: `task release` (interactive semver release with gum/svu)
 32- Full check: `task` (default runs fmt, lint, staticcheck, test, vuln, reuse)
 33
 34Single test:
 35
 36```bash
 37go test -v -run TestName ./path/to/package
 38```
 39
 40## Repository Layout
 41
 42- `main.go`: wires fang.Execute(RootCmd) and sets version from build info
 43- `cmd/`: Cobra commands
 44  - Root and top-level: `a` (archive), `m` (monitor/TUI stub), `p` (plan printout stub), `r` (resume), `s` (start)
 45  - `cmd/g/`: goal command group; `g` (show stub), `g s` (set goal stub with -t/-d)
 46  - `cmd/t/`: task command group; `t` (list stub with status filter flag), `t a` (add stub), `t u` (update stub)
 47- `internal/`:
 48  - `db/`: Badger wrapper: options, tx helpers, key builders, path hashing
 49  - `goal/`: goal document + store
 50  - `task/`: task types + store (status index, deterministic IDs)
 51  - `event/`: event types + store + payload builders
 52  - `timeutil/`: clocks and UTC helpers
 53  - `testutil/`: temp DB and test clocks
 54  - `tools/docgen/`: CLI doc generator
 55- `docs/`: additional design docs (e.g., `Potential schema.md`)
 56
 57## CLI Commands (current state)
 58
 59Commands exist and are registered, but most are stubs that print placeholder output:
 60
 61```bash
 62np s   # start session (stub)
 63np a   # archive session (stub)
 64np p   # print plan (stub)
 65np r   # resume session (stub)
 66np m   # monitor TUI (stub)
 67np g   # goal (stub); np g s -t -d flags defined
 68np t   # tasks (stub); -s status flag defined; t a/u files exist as stubs
 69```
 70
 71Fang is used for execution/versioning; Cobra provides the command tree.
 72
 73## Data Layer and Storage
 74
 75Implemented under `internal/db`, `internal/goal`, `internal/task`, `internal/event`.
 76
 77- Database options (internal/db/options.go)
 78  - Default path: `os.UserConfigDir()/nasin-pali/data`
 79  - Retries: `MaxTxnRetries` (default 5) with exponential `ConflictBackoff` (default 10ms)
 80  - `SyncWrites` defaults to true when not ReadOnly
 81  - No-op logger by default; Badger logger bridged via adapter
 82- Database helpers (internal/db/db.go)
 83  - `View(ctx, fn)` for read-only; `Update(ctx, fn)` for read-write with retries
 84  - Txn helpers: `Get`, `Set`, `Delete`, `GetJSON`, `SetJSON`, `Exists`, `Iterate`, `IncrementUint64`
 85  - Errors normalized: `ErrClosed`, `ErrReadOnly`, `ErrKeyNotFound`, `ErrTxnAborted`
 86  - Iterator uses prefix scans; `IterateOptions{Prefix, Reverse, PrefetchValues}`
 87  - Value log size set to 64 MiB when writable
 88- Keyspace builders (internal/db/keys.go)
 89  - Meta/schema: `meta/schema_version`
 90  - Per-directory: `dir/{dir_hash}/active`, `dir/{dir_hash}/archived/{ts_hex}/{sid}`
 91  - Global indexes: `idx/active/{sid}`, `idx/archived/{ts_hex}/{sid}`
 92  - Per-session: `s/{sid}/meta`, `s/{sid}/goal`, `s/{sid}/task/{id}`
 93  - Status index: `s/{sid}/idx/status/{status}/{id}`
 94  - Events: `s/{sid}/meta/evt_seq` (counter), `s/{sid}/evt/{seq_hex}`; prefixes for scans exist
 95- Path handling (internal/db/path.go)
 96  - `CanonicalizeDir`: abs + EvalSymlinks + Clean + ToSlash; lowercase on Windows
 97  - `DirHash`: blake3-256 of canonical path (hex)
 98  - `ParentWalk`: yields canonical parents up to root
 99- Encoding helpers (internal/db/encoding.go)
100  - Big-endian u64 encode/decode; `Uint64Hex` for zero-padded lower-hex
101
102## Domain Stores
103
104- Goal (internal/goal)
105  - Document: `{title, description, updated_at}` (UTC)
106  - Store: `Get`, `Exists`, `Set`; title is trimmed and required
107  - Transaction-scoped `TxnStore` mirrors operations
108- Task (internal/task)
109  - Status: `pending`, `in_progress`, `completed`, `failed`, `cancelled` with validation helpers
110  - Task: `{id, title, description, status, created_at, updated_at, created_seq}` (UTC)
111  - ID: `GenerateID(sid, title, description)` uses blake3 of normalized (trim + squash spaces) title/description + sid; first 6 hex
112  - Store: `Create`, `Get`, `Update`, `UpdateStatus`, `Delete`, `List`, `ListByStatus`, `Exists`
113  - Maintains status membership keys; sorts by `created_seq`, then `created_at`, then `id`
114- Event (internal/event)
115  - Types: `goal_set`, `goal_updated`, `task_added`, `task_updated`, `task_status_changed`
116  - Record: `{seq, at, type, reason?, cmd, payload}`; `reason` optional; `cmd` required and trimmed
117  - Store: `Append`, `List` (supports `After` and `Limit`), `LatestSequence`
118  - Sequence stored as 8-byte big-endian counter at `s/{sid}/meta/evt_seq`; keys use hex-encoded seq
119  - Payload helpers in `payloads.go` build stable snapshots for events
120
121All stores accept an optional `timeutil.Clock`; default is a UTC system clock. `timeutil.EnsureUTC` normalizes timestamps.
122
123## Testing
124
125- Tests live under `internal/*_test.go` (goal, task, event)
126- Helpers: `testutil.OpenDB(t)` opens a temp Badger DB with cleanup; `testutil.SequenceClock` yields deterministic times
127- Run: `task test` or `go test -v ./...`
128- Example single test pattern: `go test -v -run TestName ./internal/task`
129
130## Doc Generation
131
132- Tool: `internal/tools/docgen` (cobra/doc based)
133- `task docs` runs two invocations: one tree under `docs/cli/`, and a single-file reference `docs/llm-reference.md`
134- Note: the Taskfile passes `-exclude m` but `docgen` has no `-exclude` flag; adjust if this causes failures
135
136## Output Format for LLMs
137
138- Status icons: ☐ pending, ⟳ in progress, ☑ completed, ☒ failed, ⊗ cancelled (only show failed/cancelled in legend when present)
139- Commands that change state should print the full plan immediately (current CLI commands are stubs)
140
141## Conventions
142
143- Formatting: gofumpt (not `go fmt`)
144- Errors and validation follow idiomatic Go patterns visible in stores
145- All source files include SPDX headers; source is AGPL-3.0-or-later; docs/config are CC0-1.0
146
147## Gotchas
148
149- `task docs` may fail due to `-exclude` flag unsupported by docgen
150- `db.Options` sets `SyncWrites=true` by default when not read-only (durability over throughput)
151- Event sequence counter is raw 8-byte big-endian; do not store decimal strings
152- Windows: directory canonicalization lowercases paths; hashes derive from canonicalized form
153
154## Implementation Status
155
156- CLI commands exist but are stubs that print placeholders
157- Data layer (db, goal, task, event) is implemented with tests; session orchestration and wiring from CLI to stores is not yet implemented
158- `docs/Potential schema.md` captures intended end-state for sessions, indexes, and events; use as design context, not as a guarantee