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

```
main.go          → CLI dispatcher (import | sql | dataset | ...)
cmd/*.go         → CLI commands (flags → tools → JSON output)
tools/*.go       → CLI tools: sql, export, cluster, dataset, location, pattern, time, prepend
tools/calls/     → Call processing (filesystem .data/WAV, NO database access)
tools/import/    → Import operations (bulk, file, files, segments, unstructured)
tui/             → Interactive classify UI
db/              → Database connection + types + transactions
utils/*.go       → Reusable helpers (leaf package, no db import, no `*Input`/`*Output` structs)

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

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