# Skraak CLI/MCP Server

## Documentation Policy

**When making code changes, update CHANGELOG.md first, then CLAUDE.md only if architectural concepts change.**

- CHANGELOG.md: Detailed change history with rationale
- CLAUDE.md: Essential patterns, policies, and quick reference
- **keep it concise**

## Package Organization

Enforced by `depguard` in `.golangci.yml`. A package may only import from packages **below** it:

```
main.go
cmd/             → tools, tools/calls, tools/import, tui, config
tools/calls/     → audio, wav, spectrogram, datafile, mapping, utils   (filesystem only, NO db)
tools/import/    → db, wav, astro, datafile, mapping, utils            (defines own Mutator/Reader)
tools/           → db, audio, wav, spectrogram, datafile, astro, mapping, utils
tui/             → audio, wav, spectrogram, datafile, utils            (NO db, NO cmd)
db/              → wav (GainLevel alias only)
spectrogram/     → audio, wav
wav/             → audio, astro, utils
datafile/        → utils (FindFiles only)
audio/           → (stdlib + go-dsp)
astro/           → (stdlib + suncalc)
config/          → (stdlib)
mapping/         → (stdlib)
utils/           → (stdlib only — true leaf)

shell_scripts/   → end-to-end test scripts
```

**DB interface convention:** Each consumer defines its own minimal interface (`Mutator`, `Reader`, `Querier`, etc.) using `*Context` method variants only. No god-interfaces in `db/`. Two near-identical interfaces in two packages beats the wrong abstraction.

**`utils/` invariants:** no `database/sql` import, no `skraak/*` import, no `*Input`/`*Output` structs.

**use cli tool `gosymdb agent-context` for exploratory dev tools"

## Building & Running

### Build
```bash
go build -o skraak
```

### CLI Commands
```bash
# SQL query
./skraak sql --db ./db/test.duckdb "SELECT COUNT(*) FROM file WHERE active = true"
```

**CLI Design:** All tools output JSON for composability with Unix tools (jq, grep). Errors to stderr.

---

## Testing

### Go Unit Tests
```bash
go test ./...                        # All tests
go test -v ./utils/                  # Verbose
go test -cover ./utils/              # Coverage
go test -coverprofile=coverage.out ./utils/ && go tool cover -html=coverage.out
```

### Cyclomatic Complexity

Please work to reduce cyclomatic complexity. 

Endeavour to keep new code under 10.

```bash
gocyclo -over 10 .
gocyclo <file>
```

### Shell Scripts (in shell_scripts/)
```
# make sure db/test.duckdb available and FK's applied.
# 550 line output, beware token overflow
# runs all unit tests and shell script integration tests

make test
```

 🚨 Critical Database Safety
**ALWAYS Use Test Database for Testing**
```bash
cd shell_scripts
./test_sql.sh ../db/test.duckdb > test.txt 2>&1
```
- `db/skraak.duckdb` = **PRODUCTION**
- `db/test.duckdb` = **TEST** (safe for testing)
- **Always specify test.duckdb explicitly**