# NoBox Project

## Project Overview
NoBox - JSON and YAML key-value storage utilities for flexible, schema-less data storage via CLI.

Part of the [Box Suite](https://github.com/jmmirabile/confbox) - a modular Python CLI utility framework.

## Project Structure
```
nobox/
├── nobox/
│   ├── __init__.py
│   ├── drivers.py       # Driver base class, JSONDriver, YAMLDriver
│   ├── store.py         # DictStore - CRUD operations
│   ├── cli.py           # CLI command parser and executor
│   └── main.py          # Entry points for jsonbox/yamlbox
├── tests/
├── docs/
├── setup.py
├── pyproject.toml
├── README.md
├── DESIGN.md            # Complete architecture and design decisions
├── CLAUDE.md            # This file - project context
└── LICENSE
```

## Commands Provided

**Installation:**
```bash
pip install nobox
```

**Provides two commands:**
- `jsonbox` (alias: `jb`) - JSON format storage
- `yamlbox` (alias: `yb`) - YAML format storage

## Quick Reference

```bash
# Discovery (hierarchical navigation)
jb --list                      # List all databases (or jb -l, jb databases)
jb mydb --list                 # List collections in mydb (or jb mydb -l)

# CRUD operations
jb mydb users set alice name:Alice age:30  # Set record
jb mydb users get alice                    # Get record
jb mydb users keys                         # List keys
jb mydb users all                          # Show all records
jb mydb users del alice                    # Delete record

# Output formats
jb mydb users all --json       # JSON object
jb mydb users all --jsonl      # JSON Lines
jb mydb users all --oneline    # key field:value format
jb mydb users all --csv        # CSV for Excel

# Import from stdin
cat data.txt | jb mydb users import          # Bulk import records
echo "alice name:Alice age:30" | jb mydb users import  # Single record
```

## Storage Location

Uses ConfBox for cross-platform directories:

| OS | Storage Location |
|----|------------------|
| Linux | `~/.local/share/nobox/` |
| macOS | `~/Library/Application Support/nobox/` |
| Windows | `%APPDATA%\nobox\` |

**Structure:**
```
~/.local/share/nobox/
├── json/              # JSON format storage
│   └── mydb/          # Database (directory)
│       ├── users.json # Collection (file)
│       └── products.json
└── yaml/              # YAML format storage
    └── mydb/          # Same database, YAML format
        ├── users.yaml
        └── products.yaml
```

**Benefits:**
- Single storage location (easier to backup)
- Both formats can coexist for same database
- Easy migration between formats (export/import)

## Development Information

### Build Commands
```bash
pip install -e .               # Development install
pip install -e ".[dev]"        # With dev dependencies
```

### Test Commands
```bash
pytest                         # Run all tests
pytest -v                      # Verbose output
pytest tests/test_drivers.py   # Specific test file
```

### Lint Commands
```bash
# TBD - will add flake8, black, mypy
```

## Dependencies

- **Python 3.8+**
- **confbox** >= 0.1.0 - Cross-platform directory management
- **PyYAML** - YAML format support (for yamlbox)

## Key Design Decisions

1. **Single package, two entry points** - DRY principle, shared code (jsonbox/jb, yamlbox/yb)
2. **Pluggable drivers** - JSONDriver, YAMLDriver (could add TOML, etc.)
3. **Schema-less** - Flexible key:value storage, complements DBBox
4. **Multiple output formats** - Unix pipeline friendly (--json, --csv, --oneline, --jsonl)
5. **Directory = Database** - Don't load entire DB for one collection
6. **Hierarchical discovery** - Intuitive navigation from databases → collections → keys → records
7. **Case-insensitive keys** - All keys stored lowercase for consistency

## Use Cases

- Network device configuration snapshots (F5, switches, routers)
- API response caching
- Operational data storage (server inventories, etc.)
- Quick data capture (notes, todos, scratch data)
- Any nested/complex data that's awkward in flat files

## Related Projects

### Box Suite
- **[ConfBox](https://pypi.org/project/confbox/)** ✅ - Config management (published)
- **[DBBox](https://github.com/jmmirabile/dbbox)** ✅ - SQLite utility (complete)
- **NoBox** 🔨 - This project
- **PlugBox** 🔨 - Plugin system (planned)
- **CLIBox** 🔨 - CLI framework (planned)
- **APIBox** 🔨 - API testing tool (planned)

### Comparison: DBBox vs NoBox

**Use DBBox when:**
- Structured, relational data
- Fixed schema
- SQL queries needed
- Flat tabular data

**Use NoBox when:**
- Nested, complex data structures
- Variable/flexible fields
- No schema needed
- JSON/YAML natural format

## Development Status

- **Current Phase:** Core complete, ready for testing
- **Version:** 0.1.0 (pre-release)
- **Status:** Core features implemented, needs testing before release

### Completed ✅
- [x] Driver architecture (JSON, YAML)
- [x] DictStore with CRUD operations
- [x] CLI with all commands (set, get, del, keys, all, import)
- [x] Multiple output formats (table, JSON, JSONL, oneline, CSV)
- [x] Hierarchical discovery (databases, collections listing)
- [x] Command aliases (jb, yb)
- [x] Import from stdin with error handling
- [x] Comprehensive documentation (README, DESIGN, examples)
- [x] Cross-platform storage via ConfBox

### TODO Before Release 📝
1. **High Priority:**
   - [ ] Add pytest test suite (tests/ directory exists but empty)
   - [ ] Input validation (database/collection names, prevent path traversal)

2. **Medium Priority:**
   - [ ] Shell completion scripts (bash/zsh)
   - [ ] Add --version flag
   - [ ] More comprehensive error messages

3. **Nice to Have:**
   - [ ] Batch operations (set-many, del-many)
   - [ ] Query/filter capabilities
   - [ ] Backup/export entire database

## Notes

- See DESIGN.md for complete architecture documentation
- Single user tool - no concurrent access handling
- Complements DBBox (schema-less vs schema-based)
- Part of Box Suite ecosystem
- Follows Box Suite principles: modular, independent, complementary, professional

---

**Project Started:** 2026-02-06
**Working Directory:** /home/jeffmira/Documents/dev/nobox
**Git Repository:** Not yet initialized
