Skip to content

Commit 4aa4c65

Browse files
AryanSharma9917AryanSharma9917
committed
docs: add testing runbook and project overview, refresh README
1 parent eb8831f commit 4aa4c65

3 files changed

Lines changed: 317 additions & 4 deletions

File tree

‎PROJECT_OVERVIEW.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Codewise CLI Project Overview
2+
3+
## What This Project Does
4+
5+
Codewise CLI is a DevOps-focused command-line tool that unifies common workflows used in application delivery.
6+
7+
It provides one command surface for:
8+
- Dockerfile scaffolding and image build operations
9+
- Kubernetes manifest generation and apply/delete operations
10+
- Helm chart scaffolding
11+
- Deployment status/log/history/rollback flows
12+
- Environment profile management
13+
- Data transformation utilities (YAML, JSON, TOML, XML, ENV, Base64)
14+
- Template generation (for example GitHub Actions and Argo app templates)
15+
16+
The goal is to reduce command sprawl and boilerplate when moving from code to deployable workloads.
17+
18+
## How It Is Built
19+
20+
The project is implemented in Go and organized as a Cobra-based CLI.
21+
22+
High-level build path:
23+
- `main.go` is the executable entry point.
24+
- `cmd/` contains CLI command definitions and flag wiring.
25+
- `pkg/` contains implementation logic used by commands.
26+
27+
Build commands:
28+
29+
```bash
30+
go build -o codewise-cli main.go
31+
# or
32+
make build
33+
```
34+
35+
Test commands:
36+
37+
```bash
38+
make test
39+
go test ./... -v
40+
```
41+
42+
## Runtime Connectivity And Control Flow
43+
44+
The internal execution flow is:
45+
46+
1. User runs a CLI command (for example `codewise k8s apply`).
47+
2. Cobra command in `cmd/` parses args and flags.
48+
3. Command handler calls a domain package in `pkg/`.
49+
4. Domain package reads files/config and performs requested action.
50+
5. For deployment workflows, external CLIs/services are invoked where needed.
51+
6. Result is printed to terminal and process exits with success or error code.
52+
53+
Conceptual connectivity map:
54+
55+
```text
56+
Terminal User
57+
-> codewise (binary)
58+
-> cmd/* (Cobra command layer)
59+
-> pkg/* (business logic)
60+
-> Local Filesystem (templates, manifests, config)
61+
-> External Tools (docker, kubectl, helm)
62+
-> Kubernetes API (through kubectl/helm operations)
63+
```
64+
65+
## Project Structure And Responsibilities
66+
67+
- `cmd/`: Command definitions, flags, argument validation, command wiring.
68+
- `pkg/config/`: Configuration load/save defaults.
69+
- `pkg/docker/`: Dockerfile init, validation, image build helpers.
70+
- `pkg/k8s/`: Manifest generation, apply/delete orchestration.
71+
- `pkg/helm/`: Helm chart scaffold generation.
72+
- `pkg/deploy/`: Deploy planning, execution, logs, status, history, rollback.
73+
- `pkg/env/`: Environment create/list/delete behaviors.
74+
- `pkg/encoder/`: Format conversion and Base64 utilities.
75+
- `pkg/generator/`: Project and template generation logic.
76+
- `templates/`: Template source files used by template commands.
77+
- `k8s/` and `helm/`: Generated scaffold outputs.
78+
- `tests/` and `testdata/`: Test cases and fixture inputs/outputs.
79+
80+
## Tech Stack
81+
82+
Primary:
83+
- Go 1.20
84+
- Cobra CLI framework (`github.com/spf13/cobra`)
85+
- YAML support (`gopkg.in/yaml.v3`)
86+
- TOML support (`github.com/BurntSushi/toml`)
87+
- XML mapping support (`github.com/clbanning/mxj/v2`)
88+
- Interactive prompts (`github.com/AlecAivazis/survey/v2`)
89+
90+
Tooling and ecosystem dependencies:
91+
- Docker CLI and daemon for image-related workflows
92+
- kubectl and Kubernetes cluster context for K8s apply/delete workflows
93+
- Helm CLI for chart-related workflows
94+
95+
## How Commands Connect To Domains
96+
97+
- `config` commands map to config domain for defaults and view/init operations.
98+
- `docker` commands map to Docker domain for init/validate/build.
99+
- `k8s` commands map to K8s domain for scaffold/apply/delete.
100+
- `helm` commands map to Helm domain for scaffold init.
101+
- `deploy` commands map to deployment domain for run/plan/status/logs/history/rollback.
102+
- `env` commands map to environment domain for profile lifecycle.
103+
- `encode` maps to transformation domain for file format conversions.
104+
- `template` maps to generator/template domain for predefined scaffold files.
105+
106+
## Development And Contribution Model
107+
108+
Typical change flow:
109+
110+
1. Add or update command wiring under `cmd/`.
111+
2. Implement core logic in `pkg/`.
112+
3. Add or update tests under `tests/` with fixtures in `testdata/`.
113+
4. Validate with `go test ./... -v`.
114+
5. Build with `make build` and run manual smoke commands.
115+
116+
This layering keeps CLI surface concerns separate from business logic and improves testability.

‎README.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,18 +32,20 @@ Clone the repository:
3232
```bash
3333
git clone https://github.com/aryansharma9917/codewise-cli.git
3434
cd codewise-cli
35-
````
35+
```
3636

3737
Build from source:
3838

3939
```bash
40-
go build -o codewise main.go
40+
make build
41+
# or
42+
go build -o codewise-cli main.go
4143
```
4244

4345
(Optional) install globally:
4446

4547
```bash
46-
sudo mv codewise /usr/local/bin/
48+
sudo mv codewise-cli /usr/local/bin/codewise
4749
```
4850

4951
---
@@ -56,6 +58,21 @@ General syntax:
5658
codewise <command> [subcommand] [flags]
5759
```
5860

61+
Local development usage (without global install):
62+
63+
```bash
64+
./codewise-cli <command> [subcommand] [flags]
65+
# or
66+
go run . <command> [subcommand] [flags]
67+
```
68+
69+
---
70+
71+
## Documentation
72+
73+
- [Testing runbook](TESTING_RUNBOOK.md) for copy-paste test and smoke commands
74+
- [Project overview](PROJECT_OVERVIEW.md) for architecture, connectivity, build flow, and tech stack
75+
5976
---
6077

6178
## Configuration
@@ -201,9 +218,11 @@ codewise helm init
201218
.
202219
├── cmd/ # CLI commands
203220
├── pkg/ # Core logic (docker, k8s, helm, config, encode)
221+
├── templates/ # Source templates used by generators
204222
├── helm/ # Generated Helm charts
205223
├── k8s/ # Generated Kubernetes manifests
206-
├── config/ # Configuration helpers
224+
├── tests/ # Automated tests
225+
├── testdata/ # Fixtures used by tests and conversion checks
207226
├── Dockerfile
208227
├── go.mod
209228
└── main.go

‎TESTING_RUNBOOK.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Codewise CLI Testing Runbook
2+
3+
This runbook is designed for direct copy-paste testing from project root.
4+
5+
## 1) Prerequisites
6+
7+
Use these checks to confirm required tooling is available before running any workflow.
8+
9+
```bash
10+
go version
11+
docker --version
12+
kubectl version --client
13+
helm version
14+
```
15+
16+
## 2) Build And Baseline Validation
17+
18+
Build the binary, then verify command wiring and version output.
19+
20+
```bash
21+
make clean
22+
make build
23+
./codewise-cli --help
24+
./codewise-cli version
25+
go run . --help
26+
go run . version
27+
```
28+
29+
## 3) Automated Tests
30+
31+
Run the existing test suites first, then optional race and coverage checks.
32+
33+
```bash
34+
make test
35+
go test ./... -v
36+
go test ./... -race
37+
go test ./... -coverprofile=coverage.out
38+
go tool cover -func=coverage.out
39+
```
40+
41+
## 4) Top-Level Command Surface Check
42+
43+
These commands confirm every top-level command is registered and callable.
44+
45+
```bash
46+
./codewise-cli config --help
47+
./codewise-cli deploy --help
48+
./codewise-cli docker --help
49+
./codewise-cli encode --help
50+
./codewise-cli env --help
51+
./codewise-cli helm --help
52+
./codewise-cli init --help
53+
./codewise-cli k8s --help
54+
./codewise-cli template --help
55+
```
56+
57+
## 5) Config Workflow
58+
59+
This validates local configuration initialization and read-back.
60+
61+
```bash
62+
./codewise-cli config init
63+
./codewise-cli config view
64+
cat ~/.codewise/config.yaml
65+
```
66+
67+
## 6) Encode/Convert Workflow (Fixture-Based)
68+
69+
These commands validate common encode paths using files in `testdata/`.
70+
71+
```bash
72+
./codewise-cli encode -i testdata/sample.yaml -o /tmp/cw_sample_1.json
73+
./codewise-cli encode -i testdata/sample.json -o /tmp/cw_sample_2.yaml --json-to-yaml
74+
./codewise-cli encode -i testdata/sample.env -o /tmp/cw_sample_3.json --env-to-json
75+
./codewise-cli encode -i testdata/sample.txt -o /tmp/cw_sample_4.b64 --base64
76+
./codewise-cli encode -i /tmp/cw_sample_4.b64 -o /tmp/cw_sample_5.txt --base64 --decode
77+
```
78+
79+
Quick output validation for generated artifacts.
80+
81+
```bash
82+
ls -lh /tmp/cw_sample_1.json /tmp/cw_sample_2.yaml /tmp/cw_sample_3.json /tmp/cw_sample_4.b64 /tmp/cw_sample_5.txt
83+
diff -u testdata/sample.txt /tmp/cw_sample_5.txt
84+
```
85+
86+
## 7) Scaffold Generation (Local Safe)
87+
88+
Use this to validate project scaffold generation for Kubernetes and Helm.
89+
90+
```bash
91+
rm -rf helm/chart k8s/app
92+
./codewise-cli helm init
93+
./codewise-cli k8s init
94+
find helm -maxdepth 4 -type f | sort
95+
find k8s -maxdepth 4 -type f | sort
96+
```
97+
98+
## 8) Template Commands
99+
100+
These validate template generation commands.
101+
102+
```bash
103+
./codewise-cli template github-action
104+
./codewise-cli template argo-app
105+
```
106+
107+
## 9) Docker Workflow (Requires Docker Daemon)
108+
109+
Run these if Docker is available and running on your machine.
110+
111+
```bash
112+
./codewise-cli docker init
113+
./codewise-cli docker validate
114+
./codewise-cli docker build
115+
docker images | grep -i codewise
116+
```
117+
118+
## 10) Kubernetes Workflow (Dry-Run First)
119+
120+
Use dry-run for safe validation without applying to the cluster.
121+
122+
```bash
123+
./codewise-cli k8s apply --dry-run
124+
./codewise-cli k8s delete --dry-run
125+
```
126+
127+
## 11) Kubernetes Real Apply (Only On Test Cluster)
128+
129+
Run this section only when your kube context points to a non-production cluster.
130+
131+
```bash
132+
kubectl config current-context
133+
./codewise-cli k8s apply --namespace dev
134+
./codewise-cli deploy status --namespace dev
135+
./codewise-cli deploy logs --namespace dev
136+
./codewise-cli deploy history --namespace dev
137+
./codewise-cli deploy rollback --namespace dev
138+
./codewise-cli k8s delete --namespace dev
139+
```
140+
141+
## 12) Environment Command Validation
142+
143+
Use help checks and simple actions to validate env command behavior.
144+
145+
```bash
146+
./codewise-cli env --help
147+
./codewise-cli env list
148+
./codewise-cli env create dev
149+
./codewise-cli env list
150+
./codewise-cli env delete dev
151+
./codewise-cli env list
152+
```
153+
154+
## 13) Negative Testing
155+
156+
These commands validate error handling and message quality for invalid inputs.
157+
158+
```bash
159+
./codewise-cli encode -i does-not-exist.yaml -o /tmp/out.json
160+
./codewise-cli k8s apply --context definitely-not-real --dry-run
161+
./codewise-cli deploy status --namespace does-not-exist
162+
```
163+
164+
## 14) One-Line Regression Pack
165+
166+
Use this compact command for quick regression checks before pushing changes.
167+
168+
```bash
169+
make build && go test ./... -v && ./codewise-cli encode -i testdata/sample.yaml -o /tmp/reg.json && ./codewise-cli helm init && ./codewise-cli k8s init && ./codewise-cli k8s apply --dry-run
170+
```
171+
172+
## Expected Success Signals
173+
174+
- Build exits with code 0.
175+
- Test commands pass with code 0.
176+
- Encode commands generate output files and decode roundtrip matches input.
177+
- Helm and Kubernetes scaffold files are generated without runtime errors.
178+
- Dry-run commands do not mutate cluster resources and still validate command flow.

0 commit comments

Comments
 (0)