docs: add project documentation

2026-01-18 18:32:55 +01:00
parent ad79ff97c6
commit 11f7bb5b7a
5 changed files with 292 additions and 0 deletions
--- a/PROJECT.md
+++ b/PROJECT.md
@@ -0,0 +1,45 @@
+# Project: harbor-ctl
+
+## Purpose
+
+Command-line interface for managing Harbor container registry. Provides quick access to common operations without requiring the web UI or manual API calls.
+
+## Scope
+
+### In Scope
+
+- Project, repository, and artifact listing
+- Vulnerability scanning and reporting
+- SBOM retrieval and display
+- Tag management
+- Artifact deletion
+- Project configuration (auto-scan, auto-sbom)
+
+### Out of Scope
+
+- User/group management (admin-only, rare)
+- System configuration (one-time setup)
+- Replication rule creation (complex, rare)
+- Garbage collection triggers (scheduled)
+
+## Success Criteria
+
+- Modular package structure for maintainability
+- No external dependencies (stdlib only)
+- All common daily operations accessible via CLI
+- Clear, scannable output for terminal use
+- Exit codes suitable for scripting
+- Credentials managed securely (no hardcoding)
+
+## Constraints
+
+- Python 3.10+ stdlib only
+- Harbor API v2.0 compatibility
+- Must work in minimal environments (no pip install required)
+- Legacy single-file script maintained for compatibility
+
+## Assumptions
+
+- Harbor instance is accessible over HTTPS
+- User has appropriate permissions for requested operations
+- Credentials file follows established format when present
--- a/README.md
+++ b/README.md
@@ -0,0 +1,104 @@
+# harbor-ctl
+
+CLI utility for interacting with Harbor container registry API.
+
+## Installation
+
+```sh
+# Run directly from source
+PYTHONPATH=src python3 -m harbor <command>
+
+# Or install in development mode
+pip install -e .
+
+# Or use the legacy single-file script
+./harbor-ctl.py <command>
+```
+
+## Usage
+
+```
+python -m harbor <command> [options]
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `projects` | List all projects |
+| `repos <project>` | List repositories in a project |
+| `artifacts <project> <repo>` | List artifacts in a repository |
+| `info <project> <repo>` | Show artifact details |
+| `vulns <project> <repo>` | List vulnerabilities |
+| `scan <project> <repo>` | Trigger vulnerability scan |
+| `tags <project> <repo>` | List or manage tags |
+| `sbom <project> <repo>` | Get SBOM for artifact |
+| `delete <project> <repo>` | Delete artifact or tag |
+| `config <project>` | View/modify project settings |
+
+## Authentication
+
+Credentials are loaded in priority order:
+
+1. CLI arguments (`-u`, `-p`)
+2. Secrets file (`/opt/ansible/secrets/harbor/credentials.json`)
+3. Environment variables (`HARBOR_USER`, `HARBOR_PASS`)
+
+## Examples
+
+```sh
+# List projects
+python -m harbor projects
+
+# List repositories in 'library' project
+python -m harbor repos library
+
+# Show latest artifact details
+python -m harbor info library myapp
+
+# Show artifact by tag
+python -m harbor info library myapp -d v1.0.0
+
+# List high severity vulnerabilities
+python -m harbor vulns library myapp -s high
+
+# Filter vulnerabilities by package
+python -m harbor vulns library myapp -P openssl
+
+# Trigger scan and wait for completion
+python -m harbor scan library myapp --wait
+
+# Add tag to artifact
+python -m harbor tags library myapp -a production
+
+# Show SBOM
+python -m harbor sbom library myapp
+
+# Show project settings
+python -m harbor config library --show
+
+# Enable auto-scan
+python -m harbor config library --auto-scan true
+```
+
+## Project Structure
+
+```
+src/
+└── harbor/
+    ├── __init__.py      Package metadata
+    ├── __main__.py      Entry point (python -m harbor)
+    ├── cli.py           Argument parsing, main()
+    ├── client.py        API client functions
+    ├── commands.py      CLI command handlers
+    └── config.py        Credentials loading
+```
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies (stdlib only)
+
+## License
+
+MIT
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,69 @@
+# Roadmap
+
+## Phase 1: Foundation (Complete)
+
+Core functionality implemented:
+
+- [x] Project listing
+- [x] Repository listing
+- [x] Artifact listing and details
+- [x] Vulnerability display with filtering
+- [x] Scan triggering with wait
+- [x] Tag management
+- [x] SBOM retrieval
+- [x] Artifact/tag deletion
+- [x] Project configuration
+- [x] CI pipeline (syntax + lint)
+- [x] Modular package structure (`src/harbor/`)
+
+## Phase 2: Quality
+
+Code quality and maintainability improvements:
+
+- [x] Add type hints throughout
+- [x] Modular code organization
+- [ ] Add unit tests for core functions
+- [ ] Add integration tests (mock API)
+- [ ] Improve error messages
+- [x] Add `--version` flag
+- [ ] Add `--quiet` mode for scripting
+
+## Phase 3: Output
+
+Terminal output improvements:
+
+- [ ] Unicode status indicators
+- [ ] Color output (with NO_COLOR support)
+- [ ] Table alignment fixes
+- [ ] Progress indicators for long operations
+- [ ] JSON output mode for all commands
+
+## Phase 4: Features
+
+Additional functionality:
+
+- [ ] `labels` command - manage artifact labels
+- [ ] `copy` command - copy artifact between repos
+- [ ] `gc` command - show garbage collection status
+- [ ] `replication` command - list replication rules/executions
+- [ ] `quota` command - show project quota usage
+- [ ] `audit` command - show audit logs
+- [ ] Partial digest tab completion
+
+## Phase 5: Distribution
+
+Packaging and distribution:
+
+- [ ] pyproject.toml with entry points
+- [ ] Installable package (`pip install .`)
+- [ ] Man page generation
+- [ ] Shell completions (bash/zsh/fish)
+
+## Dependencies
+
+```
+Phase 1 (done) ──> Phase 2 ─┬─> Phase 3
+                            └─> Phase 4 ──> Phase 5
+```
+
+Phase 3 and 4 can proceed in parallel after Phase 2.
--- a/TASKLIST.md
+++ b/TASKLIST.md
@@ -0,0 +1,43 @@
+# Task List
+
+Active, prioritized work items.
+
+## In Progress
+
+(none)
+
+## Next Up
+
+| # | Task | Notes |
+|---|------|-------|
+| 1 | Unit tests for `client.resolve_digest()` | Core function, good test candidate |
+| 2 | Unit tests for `client.build_url()` | Simple, deterministic |
+| 3 | Mock API tests for `commands.cmd_projects()` | Start with simplest command |
+| 4 | Unicode status symbols in output | Replace dashes with box-drawing |
+| 5 | Add `--quiet` mode for scripting | Suppress headers, minimal output |
+
+## Backlog
+
+| Task | Phase |
+|------|-------|
+| ANSI color support (with NO_COLOR) | 3 |
+| JSON output mode for all commands | 3 |
+| `labels` command | 4 |
+| `copy` command | 4 |
+| `quota` command | 4 |
+| pyproject.toml with entry points | 5 |
+| Shell completions | 5 |
+
+## Completed
+
+- [x] Initial implementation
+- [x] CI pipeline setup
+- [x] Empty response body handling fix
+- [x] README documentation
+- [x] PROJECT.md, ROADMAP.md, TODO.md created
+- [x] Type hints for `api_request()` and `load_credentials()`
+- [x] `--version` flag (`-V`)
+- [x] `build_url()` helper function
+- [x] `--verify-ssl` flag for SSL certificate verification
+- [x] Modular package structure (`src/harbor/`)
+- [x] Documentation updated for new structure
--- a/TODO.md
+++ b/TODO.md
@@ -0,0 +1,31 @@
+# TODO
+
+Intake buffer for ideas, issues, and unrefined tasks.
+
+## Ideas
+
+- Support for `.harborrc` config file in home directory
+- Cache project/repo lists for faster tab completion
+- Webhook management commands
+- Robot account management
+- Retention policy display
+- Health check endpoint monitoring
+- Multi-registry support (switch between registries)
+
+## Issues
+
+- SSL verification disabled globally (should be configurable)
+- No timeout configuration for API calls
+- Delete confirmation reads stdin (breaks piping)
+- Partial digest matching fetches all artifacts (slow for large repos)
+
+## Questions
+
+- Should `--json` output be available on all commands?
+- Should we support OIDC authentication?
+- Worth adding `--dry-run` for destructive operations?
+
+## Debt
+
+- Error handling inconsistent across commands
+- Some magic numbers (column widths, timeouts)