# Remaining design decisions to unblock code generation (V1)

Lock these choices before scaffolding code. Keep scope limited to V1.

## Build baseline

- Java LTS: choose exact version (e.g., Temurin 21)
- Maven: exact version; enable Maven Wrapper
- GraalVM: exact version for native builds (macOS/Linux)
- Root/module POM structure: reactor layout, modules list, groupId/artifactId
- Java Toolchains: configure target LTS across modules

## Dependencies (pin versions)

- CLI: Picocli
- Config/JSON/YAML: Jackson (JSON), Jackson YAML (or SnakeYAML)
- JSON Schema validation: library + draft support (2020-12)
- HTTP client: choose JDK HttpClient vs OkHttp (retries/backoff, timeouts)
- Templates: Handlebars (jknack) with partials/helpers
- Crypto: BouncyCastle (PGP) for warn-only signatures in V1
- Logging: SLF4J + backend (e.g., logback) or simple JUL bridge
- Testing: JUnit 5, AssertJ, Mockito, Testcontainers, JaCoCo
- Quality: Spotless, Checkstyle, Error Prone, Qodana config

## Project/package structure

- Base package: e.g., `io.qrun.qctl`
- Modules and responsibilities:
   - `qctl-core`: entrypoint, global flags, output/rendering, completion/man
   - `qctl-shared`: config loader/merger/validation, HTTP, auth, crypto, logging
   - `qctl-qqq`, `qctl-qbit`, `qctl-qrun`, `qctl-qstudio`: mode-specific logic
   - `qctl-integration-tests`: mock-backed contract and e2e tests
- Public APIs between modules; avoid cyclic dependencies

## Config implementation

- Discovery order and precedence: built-in < global < project < env `QCTL_*` < flags
- File locations per OS (from design)
- Env var parsing: booleans, arrays, dot-path mapping; case-insensitive values where applicable
- Top-level `output` default vs `--output` override
- Error reporting: JSON Pointer paths, Problem Details for CLI validation where helpful

## Output and logging

- Output renderer: text vs `--output json` structure
- Color rules: `--color auto|always|never`
- Logging: log levels, log format (text/json) mapping, where logs vs results print (stderr/stdout)

## HTTP layer

- Client choice (JDK vs OkHttp)
- Default timeouts: connect/write/read
- Retries/backoff: exponential with jitter; respect Retry-After for 429/503
- Headers: Idempotency-Key, auth, user-agent/version

## Auth (V1)

- Device flow stub UX (OIDC), fallback for mock (`X-API-Key`)
- Token store: OS keychain by default; file fallback path/perms in V1
- Profiles: default profile selection/override rules

## Error/exit mapping

- Implement mapping from RFC7807 + HTTP codes to exit codes per the table in DESIGN-2.md
- CLI-level validation → exit 2; integrity warnings (V1) → do not fail

## qqq (templates)

- Template manifest shape (min fields for V1)
- Handlebars features enabled; default helpers; partials support
- Local vs remote template rules; trust/warn model (warn-only V1)
- Post-gen hooks execution model; `--dry-run` behavior

## qbit (packages)

- Lockfile (`qbits.lock`) read/write schema and atomicity
- Vendor directory layout; symlink strategy for linked mode (if any in V1)
- Resolution algorithm: caret ranges, dedupe, hermetic vs offline behavior
- Integrity hash algorithm (sha512) and warning text (V1 warn-only)

## qrun (package/publish)

- Jib integration: programmatic config or POM snippet injection
- OCI label injection (frozen set from DESIGN-2.md)
- Registry auth and endpoint configuration
- Verify-by-digest (HEAD OCI manifest) implementation; stub out of mock

## qstudio (offline)

- Ledger storage: path (e.g., `.qctl/ledger/`), file naming, rotation rules
- Plan output location: `plan.md` placement and overwrite behavior
- Allow/deny globbing implementation and defaults

## Cache commands

- Cache layout: templates/qbits/artifacts/trust/locks (paths per OS)
- LRU index format and eviction policy
- `cache ls`: output format (text/json)
- `cache prune`: `--max-size` parsing (e.g., KB/MB/GB); idempotency
- `cache clean --all`: safety prompts or `--yes` behavior

## Telemetry (opt-in)

- Local event storage path; retention/rotation
- Event write timing (on exit) and minimal fields (install_id, command, duration_ms, exit_code, version, os/arch, timestamp)
- No network in V1; flag `--telemetry.enabled` overrides config

## OpenAPI integration

- DTOs: generate from OpenAPI vs hand-write POJOs for V1
- If generate: generator, packages, ignore rules, and example stubbing
- Client: minimal wrapper over HTTP with typed models

## CLI UX details

- Exact command/flag grammar for each subcommand (finalize names, help text order)
- Completion/man generation wiring (Picocli autocompletion)

## Testing strategy

- Golden snapshots: file locations, update workflow, normalization of volatile data
- Schema validation against OpenAPI for JSON outputs
- Mock server startup in tests and endpoint base URL injection
- Error-path tests for 401/404/429/503 and exit code assertions
- Idempotency replay tests (201 → 200 with same key)

## CI/CD scaffolding

- CI matrix: build, test, native image for macOS/Linux; Windows jlink zip
- Static analysis (Qodana) and coverage thresholds
- Artifact publishing (archives only in V1)

---

When these are pinned, proceed to:

1) Scaffold reactor + modules, 2) Implement `qctl-core` foundation (config, logging, output), 3) Add mode-by-mode features per V1 checklist, 4) Wire tests/golden/contract, 5) Build native/jlink artifacts.