From c3b848e58bedc4bf52dca28a0fb5e3ce50cbbc46 Mon Sep 17 00:00:00 2001 From: James A Sutherland Date: Thu, 5 Feb 2026 10:11:35 -0600 Subject: [PATCH] docs(23): capture phase context Phase 23: CLI Tools (sharpdcm) - Command structure decisions documented - Output format and verbosity strategy established - Error handling and exit code scheme defined - User experience and safety defaults captured --- .planning/phases/23-cli-tools/23-CONTEXT.md | 101 ++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 .planning/phases/23-cli-tools/23-CONTEXT.md diff --git a/.planning/phases/23-cli-tools/23-CONTEXT.md b/.planning/phases/23-cli-tools/23-CONTEXT.md new file mode 100644 index 00000000..2fb8c128 --- /dev/null +++ b/.planning/phases/23-cli-tools/23-CONTEXT.md @@ -0,0 +1,101 @@ +# Phase 23: CLI Tools (sharpdcm) - Context + +**Gathered:** 2026-02-05 +**Status:** Ready for planning + + +## Phase Boundary + +Command-line toolkit for DICOM operations - single binary (`sharpdcm`) with subcommands for common workflows: dump (display file contents), store (send to PACS), find (query PACS), lint (validate files), fix (repair issues). + +This phase delivers the CLI infrastructure and core subcommands. Additional subcommands (move, get, echo) and advanced features are separate phases. + + + + +## Implementation Decisions + +### Command Structure +- **Subcommand pattern:** Single verbs (Docker-style: `sharpdcm dump`, `sharpdcm store`, `sharpdcm find`) +- **Flag support:** Both short and long forms (Unix tradition: `-v`/`--verbose`, `-o`/`--output`, `-h`/`--help`) +- **File paths:** Hybrid approach - positional for input files, flags for options (`sharpdcm dump file.dcm --output json`) +- **Directory processing:** Recursive by default - `sharpdcm dump directory/` processes all `.dcm` files automatically + +### Output Formats & Verbosity +- **Supported formats:** Human-readable text (default), JSON (`--json` or `--format json`), XML (`--format xml`) +- **Color usage:** Automatic TTY detection - colorize when outputting to terminal, plain text when piped +- **Progress reporting:** Configurable based on output destination + - TTY: Progress bar with statistics (`[=====> ] 50/100 files (5 errors)`) + - Non-TTY: Line-per-file logging (`foo.dcm ... OK`) +- **Verbosity levels:** Four-level system via flags + - `-q`/`--quiet`: Errors only + - Normal (default): Standard output + - `-v`/`--verbose`: Detailed information + - `-vv`/`--debug`: Debug-level output + +### Error Handling & Exit Codes +- **Exit code strategy:** Categorized codes + - `0`: Success + - `1`: Usage error (invalid arguments, missing flags) + - `2`: Runtime error (file not found, network failure) + - `3`: Validation error (invalid DICOM, constraint violations) +- **Error message format:** Optional verbosity - three styles available + - Terse (default): `file.dcm: invalid tag 0010,0010` + - Verbose (`-v`): `ERROR: [file.dcm] Tag (0010,0010) invalid` + - Compiler-style (`-vv`): Multi-line with context and suggestions (like Rust errors) +- **Invalid file handling:** Configurable via `--continue-on-error` flag + - Default: Fail fast (stop on first error) + - With flag: Continue processing, report errors at end +- **Network retry:** Configurable via `--retry N` flag + - Default: No automatic retries (fail immediately with clear error) + - With flag: Retry N times before failing + +### User Experience & Defaults +- **File modification safety:** + - Write to new files by default (e.g., `file.dcm` → `file.fixed.dcm`) + - Only prompt for confirmation when overwriting existing files + - Require `-f`/`--force` flag to skip confirmation and overwrite +- **Help system:** Tiered documentation + - `-h`: Brief usage summary + - `--help`: Full documentation with examples and all flags + - Man pages: Comprehensive reference documentation +- **Configuration:** Both config file and environment variables + - Config file: `~/.sharpdcm/config` for persistent defaults (output format, verbosity, PACS endpoints) + - Environment variables: `SHARPDCM_*` prefix (e.g., `SHARPDCM_OUTPUT_FORMAT`, `SHARPDCM_VERBOSITY`) + - Precedence: Flags override env vars override config file +- **PACS connection:** Flexible specification + - Connection string format: `pacs://MY_AET@host:port` + - Individual flags: `--host`, `--port`, `--aet` + - Named profiles: `--profile production` (loads from config file) + - Default behavior: Use default profile if present and nothing specified, otherwise require explicit connection details + +### Claude's Discretion +- Specific confirmation prompt wording +- Color scheme and formatting details +- Progress bar implementation library +- Config file format (TOML, YAML, JSON) +- Man page generation approach + + + + +## Specific Ideas + +- Error handling should feel like modern CLI tools (Rust compiler, ripgrep) - helpful and actionable +- Progress reporting should adapt intelligently to the context (TTY vs pipe) +- Configuration should be discoverable but not required - tool should work well out-of-box +- PACS connection profiles should make common workflows (store to production PACS) simple + + + + +## Deferred Ideas + +None - discussion stayed within phase scope + + + +--- + +*Phase: 23-cli-tools* +*Context gathered: 2026-02-05*