1# Crush Configuration Schema Generator
2
3This tool automatically generates a JSON Schema for the Crush configuration file by using Go reflection to analyze the configuration structs. The schema provides validation, autocompletion, and documentation for configuration files.
4
5## Features
6
7- **Automated Generation**: Uses reflection to automatically generate schemas from Go structs
8- **Always Up-to-Date**: Schema stays in sync with code changes automatically
9- **Comprehensive**: Includes all configuration options, types, and validation rules
10- **Enhanced**: Adds provider enums, model lists, and custom descriptions
11- **Extensible**: Easy to add new fields and modify existing ones
12
13## Usage
14
15```bash
16# Generate the schema
17go run cmd/schema/main.go > crush-schema.json
18
19# Or use the task runner
20task schema
21```
22
23## How It Works
24
25The generator:
26
271. **Reflects on Config Structs**: Analyzes the `config.Config` struct and all related types
282. **Generates Base Schema**: Creates JSON Schema definitions for all struct fields
293. **Enhances with Runtime Data**: Adds provider lists, model enums, and tool lists from the actual codebase
304. **Adds Custom Descriptions**: Provides meaningful descriptions for configuration options
315. **Sets Default Values**: Includes appropriate defaults for optional fields
32
33## Schema Features
34
35The generated schema includes:
36
37- **Type Safety**: Proper type definitions for all configuration fields
38- **Validation**: Required fields, enum constraints, and format validation
39- **Documentation**: Descriptions for all configuration options
40- **Defaults**: Default values for optional settings
41- **Provider Enums**: Current list of supported providers
42- **Model Enums**: Available models from all configured providers
43- **Tool Lists**: Valid tool names for agent configurations
44- **Cross-References**: Proper relationships between different config sections
45
46## Adding New Configuration Fields
47
48To add new configuration options:
49
501. **Add to Config Structs**: Add the field to the appropriate struct in `internal/config/`
512. **Add JSON Tags**: Include proper JSON tags with field names
523. **Regenerate Schema**: Run the schema generator to update the JSON schema
534. **Update Validation**: Add any custom validation logic if needed
54
55Example:
56```go
57type Options struct {
58 // ... existing fields ...
59
60 // New field with JSON tag and description
61 NewFeature bool `json:"new_feature,omitempty"`
62}
63```
64
65The schema generator will automatically:
66- Detect the new field
67- Generate appropriate JSON schema
68- Add type information
69- Include in validation
70
71## Using the Schema
72
73### Editor Integration
74
75Most modern editors support JSON Schema:
76
77**VS Code**: Add to your workspace settings:
78```json
79{
80 "json.schemas": [
81 {
82 "fileMatch": ["crush.json", ".crush.json"],
83 "url": "./crush-schema.json"
84 }
85 ]
86}
87```
88
89**JetBrains IDEs**: Configure in Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings
90
91### Validation Tools
92
93```bash
94# Using jsonschema (Python)
95pip install jsonschema
96jsonschema -i crush.json crush-schema.json
97
98# Using ajv-cli (Node.js)
99npm install -g ajv-cli
100ajv validate -s crush-schema.json -d crush.json
101```
102
103### Configuration Example
104
105```json
106{
107 "models": {
108 "large": {
109 "model_id": "claude-3-5-sonnet-20241022",
110 "provider": "anthropic",
111 "reasoning_effort": "medium",
112 "max_tokens": 8192
113 },
114 "small": {
115 "model_id": "claude-3-5-haiku-20241022",
116 "provider": "anthropic"
117 }
118 },
119 "providers": {
120 "anthropic": {
121 "id": "anthropic",
122 "provider_type": "anthropic",
123 "api_key": "your-api-key",
124 "disabled": false
125 }
126 },
127 "agents": {
128 "coder": {
129 "id": "coder",
130 "name": "Coder",
131 "model": "large",
132 "disabled": false
133 },
134 "custom-agent": {
135 "id": "custom-agent",
136 "name": "Custom Agent",
137 "description": "A custom agent for specific tasks",
138 "model": "small",
139 "allowed_tools": ["glob", "grep", "view"],
140 "allowed_mcp": {
141 "filesystem": ["read", "write"]
142 }
143 }
144 },
145 "mcp": {
146 "filesystem": {
147 "command": "mcp-filesystem",
148 "args": ["--root", "/workspace"],
149 "type": "stdio"
150 }
151 },
152 "lsp": {
153 "typescript": {
154 "command": "typescript-language-server",
155 "args": ["--stdio"],
156 "enabled": true
157 }
158 },
159 "options": {
160 "context_paths": [
161 "README.md",
162 "docs/",
163 ".cursorrules"
164 ],
165 "data_directory": ".crush",
166 "debug": false,
167 "tui": {
168 "compact_mode": false
169 }
170 }
171}
172```
173
174## Maintenance
175
176The schema generator is designed to be maintenance-free. As long as:
177
178- Configuration structs have proper JSON tags
179- New enums are added to the enhancement functions
180- The generator is run after significant config changes
181
182The schema will stay current with the codebase automatically.