james.maes
f751b2eb4e
- Move design docs to docs/ - Move packaging files to packaging/ - Create GitHub issues and milestones for tracking - Update workflow and README references
138 lines
5.3 KiB
Markdown
138 lines
5.3 KiB
Markdown
# 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.
|