# harvest-session-dbs

Harvest AI agent session databases from defined hosts and store them as
fixture files for testing.

## Filename pattern

Files are stored flat in the fixture directory with the naming pattern:

```
<tool>.<host>.<version>.<date>.db
```

Examples:

```
devin.srv_fedora.3000.2.17.2026-07-23.db
opencode.srv_fedora.1.18.3.2026-07-23.db
```

- **Separator**: dot `.` between parts, underscores inside names
- **Tool first**: groups all DBs from the same tool together in `ls`
- **Date**: `YYYY-MM-DD` format

With `--dump-schema`, a `.schema.sql` file is also created:

```
devin.srv_fedora.3000.2.17.2026-07-23.db
devin.srv_fedora.3000.2.17.2026-07-23.schema.sql
```

## Installation

### From DevPi (private registry)

```bash
uv tool install harvest-session-dbs
```

> Requires the DevPi index to be configured in `~/.config/uv/uv.toml`:
> ```toml
> index-strategy = "unsafe-best-match"
>
> [[index]]
> name = "devpi"
> url = "https://pypi.registry.hochguertel.work/root/dev/+simple/"
> ```

### From source

```bash
git clone https://pastoral-oyster.pikapod.net/tools/harvest-session-dbs.git
cd harvest-session-dbs
uv sync
```

## Usage

### Harvest session DBs

```bash
# Harvest from all configured hosts and tools
harvest-session-dbs harvest

# Harvest specific host and tool
harvest-session-dbs harvest --host srv-fedora --tool devin

# Dry run (show what would be harvested)
harvest-session-dbs harvest --dry-run

# Custom output directory
harvest-session-dbs harvest --output-dir /tmp/fixtures

# Also dump schema files alongside fixtures (ADR 001 Layer 5)
harvest-session-dbs harvest --dump-schema
```

### List configured hosts

```bash
harvest-session-dbs hosts
```

### List supported tools

```bash
harvest-session-dbs tools
```

### List existing fixtures

```bash
harvest-session-dbs list-fixtures
```

### Config management

```bash
# Show config file path
harvest-session-dbs config path

# Show current configuration
harvest-session-dbs config show

# Initialize a default config file
harvest-session-dbs init
```

## Configuration

The config file is `harvest-session-dbs.yaml` (found via CLI `--config`,
then `HARVEST_SESSION_DBS_CONFIG` env var, then current directory).

```yaml
hosts:
  - srv-fedora
  - vps9
  - macbook
tools:
  - devin
  - opencode
output_dir: ~/fixtures
```

### Environment variables

| Variable | Purpose |
|----------|---------|
| `HARVEST_SESSION_DBS_CONFIG` | Config file path override |
| `SESSION_FIXTURES_DIR` | Default fixture output directory |

## Supported tools

| Tool | Remote DB path | Version command |
|------|----------------|-----------------|
| `devin` | `~/.local/share/devin/cli/sessions.db` | `devin --version` |
| `opencode` | `~/.local/share/opencode/opencode.db` | `opencode --version` |

## Development

```bash
# Install
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check

# Type check
uv run mypy src/

# Run the CLI
uv run harvest-session-dbs --help
```

## License

MIT
