# 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

If called by `cmd/`, it goes in `tools/`. If called by `tools/`, it goes in `utils/`. 

**Dependency rule:** packages may only import packages below them in this list:

- **`cmd/*.go`** - CLI commands (parse flags, call tools, print JSON)
- **`tools/`** - CLI tools (one file per tool, defines input/output types)
- **`tui/`** - TUI (interactive classify UI)
- **`db/`** - Database connection, types, transactions (may import `utils/`)
- **`utils/`** - Reusable helpers (no MCP types, no `*Input`/`*Output` structs, no `db` import)

`utils/` is the leaf package — it must not import `cmd/`, `tools/`, `tui/`, or `db/`.

---

## Architecture

Two-layer architecture: tools are MCP-free, adapters bridge to MCP protocol.

```
main.go          → CLI dispatcher (import | sql | dataset | ...)
cmd/*.go         → CLI commands (flags → tools → JSON output)
tools/*.go       → Core logic (plain Go structs)
tui/             → Interactive classify UI
db/              → Database connection + types + transactions
utils/*.go       → Reusable helpers (leaf package, no db import)
```

---

## Directory Structure

```
skraak/
├── main.go                    # CLI dispatcher
├── cmd/                       # CLI commands
├── db/
├── tools/                     # tools
├── utils/                     # Reusable helpers
├── tui/                       # TUI specific code
└── shell_scripts/             # end-to-end test scripts
```

---

## 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

### Untested Code — Intentional Skips

`utils/audio_player.go` is a thin wrapper over `oto` (requires audio hardware). No testable logic without hardware; `Resample` already covered in `resample_test.go` |

### 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 well 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**