1# CLI Commands Contract: Project Initialization
2
3**Date**: 2025-01-09  
4**Context**: Command-line interface specification for project initialization
5
6## Root Command
7
8### `dumber init`
9**Purpose**: Initialize the project with all dependencies
10
11**Syntax**:
12```bash
13dumber init [OPTIONS]
14```
15
16**Options**:
17- `--dry-run`: Show what would be done without executing
18- `--force`: Overwrite existing files if present
19- `--verbose, -v`: Show detailed progress information
20- `--go-version`: Specify Go version requirement (default: auto-detect)
21
22**Examples**:
23```bash
24# Basic initialization
25dumber init
26
27# Preview mode
28dumber init --dry-run
29
30# Force reinitialize existing project
31dumber init --force --verbose
32
33# Specify Go version
34dumber init --go-version=1.21
35```
36
37**Exit Codes**:
38- `0`: Success
39- `1`: General error (invalid arguments, etc.)
40- `2`: Dependency installation failed
41- `3`: Tool installation failed
42- `4`: Project already initialized (without --force)
43
44**Output Format**:
45```
46✓ Initializing Go module: dumber
47✓ Installing CLI dependencies: cobra, viper
48✓ Installing database dependencies: sqlite3, sqlc
49✓ Installing validation: go-playground/validator
50✓ Installing testing: testify
51✓ Installing Wails v3-alpha...
52✓ Creating project structure...
53✓ Generating configuration files...
54✓ Verifying installation...
55
56Project initialized successfully!
57
58Next steps:
59  1. Review generated configs/
60  2. Run: go build ./cmd/dumber
61  3. Start development: dumber --help
62```
63
64## Subcommands
65
66### `dumber init deps`
67**Purpose**: Install only dependencies without project structure
68
69**Syntax**:
70```bash
71dumber init deps [OPTIONS]
72```
73
74**Options**:
75- `--only`: Install specific dependency category (cli|db|validation|testing|wails)
76- `--skip`: Skip specific dependency category
77- `--latest`: Use @latest for all dependencies (default)
78- `--check`: Verify dependencies without installing
79
80**Examples**:
81```bash
82# Install only CLI dependencies
83dumber init deps --only=cli
84
85# Install everything except Wails
86dumber init deps --skip=wails
87
88# Check current dependency status
89dumber init deps --check
90```
91
92### `dumber init structure`
93**Purpose**: Create project directory structure only
94
95**Syntax**:
96```bash
97dumber init structure [OPTIONS]
98```
99
100**Options**:
101- `--template`: Use specific structure template (default|minimal)
102- `--preview`: Show directory tree without creating
103
104**Examples**:
105```bash
106# Create full project structure
107dumber init structure
108
109# Preview directory layout
110dumber init structure --preview
111
112# Minimal structure (no example files)
113dumber init structure --template=minimal
114```
115
116### `dumber init config`
117**Purpose**: Generate configuration files only
118
119**Syntax**:
120```bash
121dumber init config [OPTIONS]
122```
123
124**Options**:
125- `--type`: Generate specific config (sqlc|wails|all)
126- `--overwrite`: Replace existing config files
127
128**Examples**:
129```bash
130# Generate all config files
131dumber init config
132
133# Only SQLC configuration
134dumber init config --type=sqlc
135
136# Replace existing configs
137dumber init config --overwrite
138```
139
140## Status and Information Commands
141
142### `dumber init status`
143**Purpose**: Show initialization status
144
145**Syntax**:
146```bash
147dumber init status [OPTIONS]
148```
149
150**Options**:
151- `--format`: Output format (text|json|yaml)
152- `--detailed`: Show dependency versions and paths
153
154**Output** (text format):
155```
156Project Status: ✓ Initialized
157
158Dependencies:
159  ✓ CLI (cobra v1.8.0, viper v1.18.2)
160  ✓ Database (sqlite3 v1.14.19, sqlc v1.25.0)
161  ✓ Validation (validator v10.16.0)
162  ✓ Testing (testify v1.8.4)
163  ✗ Wails (not installed)
164
165Structure:
166  ✓ cmd/, internal/, migrations/, configs/
167  ✗ Missing: tests/integration/
168
169Build Status: ✓ Ready (go build succeeds)
170```
171
172### `dumber init verify`
173**Purpose**: Verify complete installation
174
175**Syntax**:
176```bash
177dumber init verify [OPTIONS]
178```
179
180**Options**:
181- `--fix`: Attempt to fix detected issues
182- `--report`: Generate detailed verification report
183
184**Exit Codes**:
185- `0`: All verifications passed
186- `1`: Some issues detected but not critical
187- `2`: Critical issues prevent development
188
189## Error Handling
190
191### Common Error Scenarios
192
193**Dependency Installation Failures**:
194```bash
195$ dumber init
196✗ Installing database dependencies: sqlite3
197  Error: CGO_ENABLED=1 required for sqlite3
198  Suggestion: Run 'export CGO_ENABLED=1' and try again
199  Exit Code: 2
200```
201
202**System Dependency Missing**:
203```bash
204$ dumber init
205✗ Installing Wails v3-alpha
206  Error: libwebkit2gtk-4.0-dev not found
207  Suggestion: Install with 'sudo apt install libwebkit2gtk-4.0-dev'
208  Exit Code: 3
209```
210
211**Project Already Exists**:
212```bash
213$ dumber init
214✗ Project already initialized
215  Use --force to reinitialize or run 'dumber init status'
216  Exit Code: 4
217```
218
219## Integration with Other Systems
220
221### CI/CD Integration
222Commands designed for automated environments:
223```bash
224# Non-interactive initialization
225dumber init --verbose > init.log 2>&1
226
227# Verification in CI
228dumber init verify --report=ci-report.json
229```
230
231### Development Workflow Integration
232```bash
233# Quick setup for new contributors
234git clone <repo> && cd <repo>
235dumber init
236go test ./...
237```
238
239### IDE Integration
240Status command provides machine-readable output:
241```bash
242dumber init status --format=json | jq '.dependencies.wails.status'
243```
244
245This CLI contract supports the initialization phase while providing flexibility for different development scenarios and debugging needs.