0
# Generate Command
1
2
> **NOTE**: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.
3
4
The `generate` command creates an architecture shell from a CALM pattern file with interactive prompts for pattern options. This is useful for quickly scaffolding new CALM architectures based on reusable patterns.
5
6
## Capabilities
7
8
### Generate Command
9
10
Generates a CALM architecture from a pattern file by prompting the user to select from pattern-defined options.
11
12
```typescript { .api }
13
/**
14
* Generate an architecture from a CALM pattern file
15
* @command calm generate [options]
16
*/
17
interface GenerateCommandOptions {
18
/** Path to pattern file (file path or CalmHub URL)
19
* CLI flags: -p, --pattern <file>
20
* Required: yes
21
*/
22
pattern: string;
23
24
/** Output path for generated architecture
25
* CLI flags: -o, --output <file>
26
* Default: "architecture.json"
27
*/
28
output?: string;
29
30
/** Path to directory containing meta schemas
31
* CLI flags: -s, --schema-directory <path>
32
*/
33
schemaDirectory?: string;
34
35
/** URL to CALMHub instance for remote pattern/schema loading
36
* CLI flags: -c, --calm-hub-url <url>
37
*/
38
calmHubUrl?: string;
39
40
/** Enable verbose logging
41
* CLI flags: -v, --verbose
42
* Default: false
43
*/
44
verbose?: boolean;
45
}
46
```
47
48
**Usage Examples:**
49
50
```bash
51
# Basic usage with local pattern file
52
calm generate -p pattern.json
53
54
# Specify custom output location
55
calm generate -p pattern.json -o my-architecture.json
56
57
# Use pattern from CALMHub URL
58
calm generate -p https://calmhub.example.com/patterns/api-gateway.json
59
60
# Use pattern with custom schema directory
61
calm generate -p pattern.json -s ./custom-schemas
62
63
# Enable verbose logging for debugging
64
calm generate -p pattern.json -v
65
```
66
67
## Pattern Options
68
69
Patterns can define options that users select during generation:
70
71
### OneOf Options
72
73
User must select exactly one choice from the available options:
74
75
```json
76
{
77
"oneOf": [
78
{ "description": "REST API", "nodes": [...] },
79
{ "description": "GraphQL API", "nodes": [...] }
80
]
81
}
82
```
83
84
The CLI presents these as a single-selection list prompt.
85
86
### AnyOf Options
87
88
User can select zero or more choices from the available options:
89
90
```json
91
{
92
"anyOf": [
93
{ "description": "Authentication", "nodes": [...] },
94
{ "description": "Rate Limiting", "nodes": [...] },
95
{ "description": "Caching", "nodes": [...] }
96
]
97
}
98
```
99
100
The CLI presents these as a multi-selection checkbox prompt.
101
102
## Configuration
103
104
### CALMHub Integration
105
106
When using CALMHub for remote pattern loading:
107
108
1. **Via Command-Line Option:**
109
110
```bash
111
calm generate -p my-pattern.json -c https://calmhub.example.com
112
```
113
114
2. **Via User Configuration File (`~/.calm.json`):**
115
116
```json
117
{
118
"calmHubUrl": "https://calmhub.example.com"
119
}
120
```
121
122
The command-line option takes precedence over the configuration file setting.
123
124
### Schema Directory
125
126
Patterns are validated against CALM meta schemas. You can specify a custom schema directory:
127
128
```bash
129
calm generate -p pattern.json -s ./path/to/schemas
130
```
131
132
If not specified, the default schema directory from `@finos/calm-shared` is used.
133
134
## Output
135
136
The generate command creates a JSON file containing the generated CALM architecture. The architecture includes:
137
138
- All nodes, relationships, and other components defined in the pattern
139
- Values based on the user's selected options
140
- Placeholder values (marked with `-1` for numbers, `"PLACEHOLDER"` for strings) that need to be filled in
141
142
Example output structure:
143
144
```json
145
{
146
"$schema": "https://calm.finos.org/schemas/calm-v1.json",
147
"nodes": [
148
{
149
"unique-id": "api-gateway",
150
"node-type": "system",
151
"name": "API Gateway",
152
"interfaces": [
153
{
154
"unique-id": "rest-api",
155
"host": "PLACEHOLDER",
156
"port": -1
157
}
158
]
159
}
160
]
161
}
162
```
163
164
Users should replace placeholder values with actual values for their architecture.
165
166
## Workflow
167
168
1. **Pattern Loading:**
169
- Load pattern from file path or URL
170
- Validate pattern structure
171
- Extract options from pattern
172
173
2. **User Interaction:**
174
- Present options to user via interactive prompts
175
- Collect user selections (oneOf as radio, anyOf as checkboxes)
176
- Validate selections against pattern constraints
177
178
3. **Architecture Generation:**
179
- Build schema directory for validation
180
- Generate architecture based on pattern and selections
181
- Apply selected options to architecture structure
182
183
4. **Output:**
184
- Write generated architecture to specified output file
185
- Report any errors or warnings
186
187
## Error Handling
188
189
Common errors and their meanings:
190
191
### Pattern Loading Errors
192
193
**Error:** `Failed to load pattern from <path>`
194
195
**Cause:** Pattern file not found or URL unreachable
196
197
**Solution:** Verify pattern path/URL is correct and accessible
198
199
### Schema Validation Errors
200
201
**Error:** `Pattern validation failed`
202
203
**Cause:** Pattern does not conform to CALM pattern schema
204
205
**Solution:** Validate pattern structure against CALM pattern schema
206
207
### Option Selection Errors
208
209
**Error:** `The choice of [<value>] is not a valid choice in the pattern`
210
211
**Cause:** Internal error where invalid option was selected
212
213
**Solution:** This should not occur in normal usage; report as a bug
214
215
### File Write Errors
216
217
**Error:** `Failed to write output file`
218
219
**Cause:** Permission denied or invalid output path
220
221
**Solution:** Verify output directory exists and is writable
222
223
## Integration with Other Commands
224
225
The generate command is typically the first step in a CALM workflow:
226
227
1. **Generate** → Creates architecture shell from pattern
228
2. **Edit** → User fills in placeholder values
229
3. **Validate** → Verify architecture conforms to pattern
230
4. **Template/Docify** → Generate code or documentation from architecture
231
232
Example workflow:
233
234
```bash
235
# Step 1: Generate architecture from pattern
236
calm generate -p api-gateway-pattern.json -o my-api.json
237
238
# Step 2: Edit my-api.json to replace placeholders
239
# (manual editing)
240
241
# Step 3: Validate the completed architecture
242
calm validate -a my-api.json -p api-gateway-pattern.json
243
244
# Step 4: Generate documentation
245
calm docify -a my-api.json -o ./docs
246
```
247
248
## Types
249
250
```typescript { .api }
251
// Pattern option types from @finos/calm-shared
252
interface CalmOption {
253
optionType: 'oneOf' | 'anyOf';
254
prompt: string;
255
choices: CalmChoice[];
256
}
257
258
interface CalmChoice {
259
description: string;
260
nodes?: any[];
261
relationships?: any[];
262
// ... other CALM components
263
}
264
265
// Document loader configuration
266
interface DocumentLoaderOptions {
267
calmHubUrl?: string;
268
schemaDirectoryPath?: string;
269
debug: boolean;
270
}
271
```
272