promocrypt-cli 1.1.0

# CLAUDE.md — promocrypt-cli

> **Command-line interface for promotional code generation and validation**

---

## CRITICAL RULES

### 1. DOCUMENTATION FIRST (MANDATORY)

**Before making ANY code changes:**

1. **Update docs/ files FIRST** - Any logical changes, new features, or modifications require updating the relevant documentation files BEFORE writing code
2. **Update README.md** - Ensure README reflects current state, no outdated information
3. **Verify consistency** - Check that docs match the actual implementation

**This is REQUIRED. Users must never encounter outdated documentation or be unaware of changes.**

### 2. CLI is a Thin Wrapper

- CLI wraps promocrypt-core - don't duplicate core logic
- Use core's validation, generation, encryption directly
- CLI adds: database integration, output formatting, configuration

### 3. Exit Codes Matter

Scripts depend on exit codes. Always use correct codes:

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Validation failed |
| 2 | File error |
| 3 | Auth error |
| 4 | Database error |
| 5 | Config error |
| 6 | Exec error |
| 7 | Not found |

### 4. JSON Mode Compatibility

When `-J` flag is used:
- All output must be valid JSON
- Success: `{"ok": true, "data": {...}}`
- Error: `{"ok": false, "error": {...}}`
- Never mix plain text with JSON output

### 5. Database Security

- Never log passwords or connection strings with credentials
- Escape all SQL identifiers and values
- Use parameterized queries where possible

---

## Quick Reference

```bash
# Create project
promocrypt create production -p "secret"

# Generate codes
promocrypt generate 1000 -d "postgres://..." -t codes

# Validate
promocrypt validate "ABC123DEF0"
promocrypt validate -f codes.txt --summary

# Info
promocrypt info

# Database operations
promocrypt lookup "ABC123" -d "postgres://..."
promocrypt export -o codes.csv -F csv
```

---

## Project Structure

```
cli/
├── src/
│   ├── main.rs          # Entry point
│   ├── cli.rs           # Clap argument definitions
│   ├── error.rs         # CLI error types
│   ├── output.rs        # Output formatting
│   ├── config.rs        # Configuration handling
│   ├── paths.rs         # Path resolution
│   ├── database/
│   │   ├── mod.rs       # Database trait
│   │   ├── postgres.rs  # PostgreSQL implementation
│   │   └── sqlite.rs    # SQLite implementation
│   └── commands/
│       ├── create.rs
│       ├── generate.rs
│       ├── validate.rs
│       ├── info.rs
│       ├── lookup.rs
│       ├── stats.rs
│       ├── export.rs
│       ├── master.rs
│       ├── config.rs
│       ├── rotate_secret.rs
│       ├── history.rs
│       ├── generation_log.rs
│       ├── pg_import.rs
│       ├── pg_export.rs
│       ├── init.rs
│       ├── list.rs
│       ├── remove.rs
│       ├── doctor.rs
│       ├── update.rs
│       └── completions.rs
├── docs/
│   ├── commands.md      # All commands reference
│   ├── database.md      # Database integration
│   ├── configuration.md # Config hierarchy
│   ├── output-formats.md # Output formats
│   └── errors.md        # Exit codes, errors
└── tests/
```

---

## Documentation Index

| Document | Contents |
|----------|----------|
| [docs/commands.md](docs/commands.md) | Complete command reference with all options |
| [docs/database.md](docs/database.md) | PostgreSQL, SQLite, typed columns, external commands |
| [docs/configuration.md](docs/configuration.md) | Config hierarchy, TOML/JSON format, paths |
| [docs/output-formats.md](docs/output-formats.md) | Plain, JSON, CSV, TSV, JSON mode |
| [docs/errors.md](docs/errors.md) | Exit codes, error types, scripting tips |

---

## Key Features

### Database Integration

```bash
# PostgreSQL
promocrypt generate 10000 \
  -d "postgres://user:pass@localhost/db" \
  -t promo_codes \
  -I campaign_id=123 \
  -N created_at

# SQLite
promocrypt generate 1000 \
  -d "sqlite:///codes.db" \
  -t codes
```

### Typed Columns

```bash
-x campaign="Summer"      # String
-I discount_percent=20    # Integer
-B active=true            # Boolean
-N created_at             # Timestamp (NOW)
--set-json meta='{...}'   # JSON
--set-null expires_at     # NULL
```

### Output Formats

```bash
-F plain    # One per line (default)
-F json     # JSON array
-F csv      # CSV with headers
-F tsv      # Tab-separated
```

### Configuration Hierarchy

1. Command-line arguments
2. Environment variables
3. Local config (`.promocrypt.toml`)
4. User config (`~/.config/promocrypt/`)
5. System config (`/etc/promocrypt/`)

---

## Build & Test

```bash
# Build
cargo build --release

# Test
cargo test

# Install
cargo install --path .

# Generate completions
promocrypt completions bash > ~/.bash_completion.d/promocrypt
```