opusr-client/CLAUDE.md

# OpusR-Client — Project Instructions

## Project Overview
Rust CLI/TUI client for opusR Monitor (z/OS RACF security analysis).
Connects to DB2 Native REST Services on z/OS via HTTPS.
Designed for distribution to enterprise customers with z/OS RACF installations.

## Architecture
```
OpusR-Client (Rust binary)
  │
  ├── Auth: RACF login → PassTicket (one-time, 10min TTL)
  ├── API:  HTTPS POST → DB2 DDF Native REST → JSON
  └── UI:   Terminal TUI (ratatui) or JSON stdout
```

- **No middleware**: direct HTTPS to DB2 DDF on z/OS
- **Auth**: Initial RACF login, then PassTicket-based (no password stored)
- **Transport**: TLS mandatory (DDF SECPORT), certificate validation
- **Data**: Read-only SELECT queries, JSON responses

## z/OS Backend (3 REST Services)
1. `opusrTables` — list tables in OPUSR schema (→ main menu)
2. `opusrColumns` — list columns for a table (→ selection panel)
3. `opusrQuery` — dynamic query via Stored Procedure (→ data view)

All services use HTTP POST to DB2 DDF.
Parameters are positional: P1, P2, P3... (DB2ServiceManager convention).

## Tech Stack
- Rust 2021 edition, MSRV 1.75
- `reqwest` — HTTPS client with native-tls
- `serde` / `serde_json` — JSON serialization
- `ratatui` + `crossterm` — terminal UI
- `clap` — CLI argument parsing
- `secrecy` — password/token handling (zeroize on drop)
- `keyring` — OS keychain for session tokens (optional)
- `tokio` — async runtime

## Security Requirements (CRITICAL)
- Passwords NEVER stored on disk, NEVER logged, NEVER in error messages
- Use `secrecy::SecretString` for all credential handling
- PassTickets stored only in memory, refreshed before expiry
- TLS certificate validation ON by default (--danger-accept-invalid-certs for dev only)
- No panics in production paths — use Result<T, E> everywhere
- Audit log: every REST call logged (without credentials)

## Code Style
- `cargo clippy -- -D warnings` must pass
- `cargo fmt` applied before every commit
- No `unwrap()` or `expect()` except in tests
- Error types: use `thiserror` for library errors, `anyhow` in main
- Doc comments on all public items
- German comments OK for business logic, code identifiers in English

## Development Workflow (Self-Steering Loop)

### After every code change:
1. `cargo fmt --check` — formatting
2. `cargo clippy -- -D warnings` — lints
3. `cargo test` — all tests
4. `cargo build --release` — verify release build
5. If ANY step fails → fix immediately, restart from step 1
6. Only proceed when all 4 steps pass

### When adding a new feature:
1. Plan in `tasks/todo.md`
2. Define types in `src/models/`
3. Write tests first (TDD)
4. Implement
5. Run full cycle
6. Mark complete in `tasks/todo.md`

### After ANY correction from the user:
- Update `tasks/lessons.md` with what went wrong
- Write a rule that prevents the same mistake

## DB2 REST Response Format
```json
{
  "ResultSet Output": [
    {"COL1": "value", "COL2": 123},
    {"COL1": "value2", "COL2": 456}
  ]
}
```
- Column names are UPPERCASE
- CHAR fields are right-padded with spaces → always trim
- NULL values: field is absent from JSON object
- Errors: HTTP 400/401/403/500 with JSON error body

## Project Structure
```
src/
  main.rs          — CLI entry point, argument parsing
  api/
    mod.rs         — REST client, request/response handling
    client.rs      — DB2RestClient struct
    services.rs    — opusrTables, opusrColumns, opusrQuery
  auth/
    mod.rs         — authentication module
    login.rs       — RACF login flow
    passticket.rs  — PassTicket management (refresh, expire)
  config/
    mod.rs         — configuration (host, port, schema, TLS)
    settings.rs    — CLI args + config file + env vars
  models/
    mod.rs         — data types
    table.rs       — TableInfo, ColumnInfo
    query.rs       — QueryFilter, QueryResult
    error.rs       — OpusrError enum
  tui/
    mod.rs         — terminal UI (ratatui)
    app.rs         — app state machine
    views/         — table list, column select, data view
tests/
  integration.rs   — integration tests with mock server
  api_tests.rs     — API client unit tests
docs/
  architecture.md  — design decisions
  security.md      — security model documentation
tasks/
  todo.md          — task tracker
  lessons.md       — learned mistakes
```