README
¶
Toolkit
Toolkit is a collection of reusable Go components exposed through a modular CLI and optional TUI (built with Bubble Tea).
It targets day-to-day DevOps & development automation: querying Kubernetes, parsing Terraform plans, mass-editing config files, and inspecting large data tables directly in your terminal.
Feature Highlights
| Area | Packages | Notes |
|---|---|---|
| CLI core | internal/cli |
Cobra-based, flags auto-generated |
| Interactive TUI | internal/ui/tui |
Sort/search/filter large tabular datasets |
| Infrastructure loaders | internal/infra/k8s, internal/infra/terraform |
Uniform abstraction for K8s & TF |
| Config loading & validation | internal/config, internal/configloader |
JSON / YAML with defaulting & schema checks |
| Collections helpers | internal/collections |
Generic filter/sort with predicates |
| Encoding helpers | internal/encoding/jsonutil |
Fast JSON pointer traversal |
| Error & logging | internal/errors, internal/infra/logging |
Typed errors, zap logger |
Install
# Latest release
go install github.com/jingle2008/toolkit/cmd/toolkit@latest
# From source
git clone https://github.com/jingle2008/toolkit.git
cd toolkit && make
Usage
toolkit --help # all global flags
Global Flags
| Flag | Default | Description |
|---|---|---|
--config, -c |
n/a | Path to YAML/JSON config file |
--format, -o |
table |
Output: table/json/yaml |
--log-level |
info |
zap log level |
--no-color |
false |
Disable ANSI colors |
(See internal/cli/root.go for the authoritative list.)
Project Layout
.
├── cmd/
│ └── toolkit/ # main()
├── internal/
│ ├── cli/ # cobra root & sub-commands
│ ├── ui/tui/ # Bubble Tea models & views
│ ├── infra/
│ │ ├── k8s/ # K8s data sources
│ │ └── terraform/ # Terraform provider
│ ├── config/ # typed config structs
│ ├── configloader/ # env + file loader
│ ├── collections/ # generic filter/sort
│ ├── encoding/jsonutil/ # JSON helpers
│ └── errors/ # error helpers
└── test/
└── integration/
Build
make
or
go build -o bin/toolkit ./cmd/toolkit
Run
./bin/toolkit --help
or, if built with Go:
go run ./cmd/toolkit --help
Testing
Run all tests with:
go test ./...
Running tests
- Unit tests (default):
make test - Integration tests (with build tag):
make test-int - Coverage reports:
make cover # unit test coverage make cover-int # integration test coverage
Continuous Integration
- Unit tests run on all pushes and pull requests.
- Integration tests run on pushes to
mainand nightly (see.github/workflows/ci.yml). - CI target: Run
make cito execute both lint and test in one step (recommended for local and CI use).
Developer Workflow
- Run
make cibefore pushing to ensure code passes lint and tests. - Use
make lintto check for style and static analysis issues. - Use
make testfor a full race-enabled test run. - Use
make fmtandmake tidyto auto-format and tidy dependencies.
Architecture Overview
Toolkit follows a modular, testable architecture:
- Loader interfaces (see
internal/app/toolkit/loader.go): Abstract data loading for datasets, models, GPU pools, etc. Split by concern for testability and clean dependency injection. - Renderer interfaces (see
internal/app/toolkit/render.go): Abstract rendering logic for different output formats (e.g., JSON, table). - Model (see
internal/app/toolkit/model.go): Central state and update logic, using the Bubble Tea TUI pattern. Composed via functional options for flexibility. - Category enum (see
internal/app/toolkit/category.go): Strongly-typed, extensible grouping for all toolkit data and UI.
Logging
Toolkit uses zap for structured, machine-readable logging. Logs are written to debug.log by default.
Contributing
Contributions are welcome! Please open issues or submit pull requests for new features, bug fixes, or improvements.
License
This project is licensed under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
toolkit
command
Package main is the entry point for the toolkit CLI application.
|
Package main is the entry point for the toolkit CLI application. |
|
internal
|
|
|
cli
Package cli provides the root command and CLI entrypoint for the toolkit application.
|
Package cli provides the root command and CLI entrypoint for the toolkit application. |
|
collections
Package collections provides generic collection utilities for filtering and sorting.
|
Package collections provides generic collection utilities for filtering and sorting. |
|
config
Package config provides configuration loading and validation for the toolkit CLI application.
|
Package config provides configuration loading and validation for the toolkit CLI application. |
|
configloader
Package configloader provides utilities for loading configuration overrides and tenancy data for the toolkit.
|
Package configloader provides utilities for loading configuration overrides and tenancy data for the toolkit. |
|
domain
Package domain defines core business types and category enums for the toolkit application.
|
Package domain defines core business types and category enums for the toolkit application. |
|
encoding/jsonutil
Package jsonutil provides utility functions for working with JSON files, including secure file loading and pretty-printing of JSON data.
|
Package jsonutil provides utility functions for working with JSON files, including secure file loading and pretty-printing of JSON data. |
|
errors
Package errors provides error helpers and sentinel errors for the toolkit application.
|
Package errors provides error helpers and sentinel errors for the toolkit application. |
|
fileutil
Package fs provides utility functions for directory operations, such as listing files with a specific extension.
|
Package fs provides utility functions for directory operations, such as listing files with a specific extension. |
|
infra/k8s
Package k8s provides helper functions for interacting with Kubernetes clusters and related resources.
|
Package k8s provides helper functions for interacting with Kubernetes clusters and related resources. |
|
infra/loader
Package loader defines interfaces for loading datasets and related resources in the toolkit application.
|
Package loader defines interfaces for loading datasets and related resources in the toolkit application. |
|
infra/loader/production
Package production provides the production Loader implementation for the toolkit application.
|
Package production provides the production Loader implementation for the toolkit application. |
|
infra/logging
Package logging provides context-based logging utilities and a generic logging interface for the toolkit application.
|
Package logging provides context-based logging utilities and a generic logging interface for the toolkit application. |
|
infra/terraform
Package terraform provides functions for loading and managing infrastructure data from Terraform state and configuration.
|
Package terraform provides functions for loading and managing infrastructure data from Terraform state and configuration. |
|
testutil
Package testutil provides assertion helpers for testing, wrapping testify's assert and require.
|
Package testutil provides assertion helpers for testing, wrapping testify's assert and require. |
|
ui/tui
Package tui provides filter and debounce utilities for the TUI model.
|
Package tui provides filter and debounce utilities for the TUI model. |
|
ui/tui/common
Package common provides shared types and utilities for the TUI components.
|
Package common provides shared types and utilities for the TUI components. |
|
ui/tui/keys
Package keys provides key binding definitions and utilities for the TUI.
|
Package keys provides key binding definitions and utilities for the TUI. |
|
ui/tui/view
Package view provides utilities for rendering and centering text in the TUI.
|
Package view provides utilities for rendering and centering text in the TUI. |
|
pkg
|
|
|
models
Package models provides data structures for toolkit models.
|
Package models provides data structures for toolkit models. |
Click to show internal directories.
Click to hide internal directories.