0
# Template Command
1

2
> **NOTE**: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.
3

4
The `template` command generates files from a CALM model using Handlebars templates. It supports template bundles, single template files, or directories of templates, enabling code generation, configuration file creation, and custom output formats from CALM architectures.
5

6
## Capabilities
7

8
### Template Command
9

10
Generate files from a CALM model using templates.
11

12
```typescript { .api }
13
/**
14
 * Generate files from a CALM model using a template bundle, single file, or directory
15
 * @command calm template [options]
16
 */
17
interface TemplateCommandOptions {
18
  /** Path to CALM architecture JSON file
19
   * CLI flags: -a, --architecture <file>
20
   * Required: yes
21
   */
22
  architecture: string;
23

24
  /** Path to output directory or file
25
   * CLI flags: -o, --output <file>
26
   * Required: yes
27
   */
28
  output: string;
29

30
  /** Delete output directory contents before processing
31
   * CLI flags: --clear-output-directory
32
   * Default: false
33
   */
34
  clearOutputDirectory?: boolean;
35

36
  /** Path to template bundle directory
37
   * CLI flags: -b, --bundle <path>
38
   */
39
  bundle?: string;
40

41
  /** Path to single .hbs or .md template file
42
   * CLI flags: -t, --template <path>
43
   */
44
  template?: string;
45

46
  /** Path to directory of .hbs/.md templates
47
   * CLI flags: -d, --template-dir <path>
48
   */
49
  templateDir?: string;
50

51
  /** Path to JSON file mapping URLs to local file paths
52
   * CLI flags: -u, --url-to-local-file-mapping <path>
53
   */
54
  urlToLocalFileMapping?: string;
55

56
  /** Enable verbose logging
57
   * CLI flags: -v, --verbose
58
   * Default: false
59
   */
60
  verbose?: boolean;
61
}
62
```
63

64
**Requirements:**
65
- Exactly one of `bundle`, `template`, or `templateDir` must be specified
66
- Cannot use multiple template source options simultaneously
67

68
**Usage Examples:**
69

70
```bash
71
# Using a template bundle
72
calm template -a architecture.json -b ./template-bundle -o ./output
73

74
# Using a single template file
75
calm template -a architecture.json -t ./template.hbs -o ./output.txt
76

77
# Using a directory of templates
78
calm template -a architecture.json -d ./templates -o ./output
79

80
# Clear output directory before generation
81
calm template -a architecture.json -b ./bundle -o ./output --clear-output-directory
82

83
# With URL-to-local-file mapping
84
calm template -a architecture.json -b ./bundle -o ./output -u ./url-mappings.json
85

86
# With verbose logging
87
calm template -a architecture.json -b ./bundle -o ./output -v
88
```
89

90
## Template Types
91

92
### Template Bundle
93

94
A template bundle is a directory containing:
95
- `index.json`: Bundle configuration defining template structure
96
- Handlebars template files (`.hbs`)
97
- Supporting files and resources
98
- Optional transformer implementation
99

100
**Bundle Structure Example:**
101

102
```
103
template-bundle/
104
├── index.json
105
├── main.hbs
106
├── partials/
107
│   ├── header.hbs
108
│   └── footer.hbs
109
└── helpers/
110
    └── custom-helpers.js
111
```
112

113
**Usage:**
114

115
```bash
116
calm template -a architecture.json -b ./template-bundle -o ./output
117
```
118

119
### Single Template File
120

121
A single Handlebars or Markdown template file for simple transformations.
122

123
**Usage:**
124

125
```bash
126
# Handlebars template
127
calm template -a architecture.json -t ./template.hbs -o ./output.html
128

129
# Markdown template
130
calm template -a architecture.json -t ./template.md -o ./output.md
131
```
132

133
### Template Directory
134

135
A directory containing multiple template files, each processed independently.
136

137
**Directory Structure Example:**
138

139
```
140
templates/
141
├── api.hbs
142
├── database.hbs
143
├── frontend.hbs
144
└── README.md.hbs
145
```
146

147
**Usage:**
148

149
```bash
150
calm template -a architecture.json -d ./templates -o ./output
151
```
152

153
Each template file generates a corresponding output file with the same name (minus `.hbs` extension).
154

155
## Handlebars Templates
156

157
Templates use Handlebars syntax with access to the CALM architecture model.
158

159
### Template Variables
160

161
Templates have access to the complete CALM architecture:
162

163
```handlebars
164
{{!-- Access nodes --}}
165
{{#each nodes}}
166
  Node: {{this.name}}
167
  Type: {{this.node-type}}
168
  ID: {{this.unique-id}}
169
{{/each}}
170

171
{{!-- Access relationships --}}
172
{{#each relationships}}
173
  From: {{this.relationship-type.connects.source.node}}
174
  To: {{this.relationship-type.connects.destination.node}}
175
{{/each}}
176

177
{{!-- Access metadata --}}
178
Schema: {{$schema}}
179
```
180

181
### Built-in Helpers
182

183
Handlebars provides standard helpers:
184
- `{{#each}}` - Iterate over arrays
185
- `{{#if}}` - Conditional rendering
186
- `{{#unless}}` - Negative conditional
187
- `{{#with}}` - Change context
188

189
### Custom Helpers
190

191
Template bundles can provide custom helpers for specialized transformations.
192

193
## URL-to-Local-File Mapping
194

195
When CALM models reference external URLs (e.g., for flows or patterns), you can map these to local files for offline processing.
196

197
### Mapping File Format
198

199
```json
200
{
201
  "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json",
202
  "https://calm.finos.org/patterns/api-gateway": "patterns/api-gateway.json"
203
}
204
```
205

206
**Path Resolution:**
207
- Paths are relative to the mapping file's directory
208
- Absolute paths are also supported
209

210
### Usage
211

212
```bash
213
calm template \
214
  -a architecture.json \
215
  -b ./template-bundle \
216
  -o ./output \
217
  -u ./url-mappings.json
218
```
219

220
When the template processor encounters a URL reference in the architecture, it will load the content from the mapped local file instead of fetching from the URL.
221

222
## Output Behavior
223

224
### Default Behavior
225

226
- Output directory is created if it doesn't exist
227
- Existing files are modified if they match template output names
228
- Unrelated files in output directory remain unchanged
229

230
### Clear Output Directory
231

232
With `--clear-output-directory` flag:
233

234
```bash
235
calm template -a architecture.json -b ./bundle -o ./output --clear-output-directory
236
```
237

238
**Warning:** This completely deletes all files and subdirectories in the output directory before generation. Use with caution!
239

240
## Template Processing Modes
241

242
The CLI uses different processing modes from `@finos/calm-shared`:
243

244
### Bundle Mode
245

246
```typescript
247
mode: 'bundle'
248
templatePath: './template-bundle'
249
```
250

251
Processes a complete template bundle with configuration.
252

253
### Template Mode
254

255
```typescript
256
mode: 'template'
257
templatePath: './template.hbs'
258
```
259

260
Processes a single template file.
261

262
### Template Directory Mode
263

264
```typescript
265
mode: 'template-directory'
266
templatePath: './templates'
267
```
268

269
Processes all templates in a directory.
270

271
## Common Use Cases
272

273
### Code Generation
274

275
Generate source code from CALM architectures:
276

277
```handlebars
278
{{!-- api.hbs --}}
279
// Generated API interfaces from CALM architecture
280

281
{{#each nodes}}
282
{{#if (eq this.node-type "service")}}
283
export interface {{this.name}}Service {
284
  {{#each this.interfaces}}
285
  // {{this.protocol}} interface on {{this.host}}:{{this.port}}
286
  {{/each}}
287
}
288
{{/if}}
289
{{/each}}
290
```
291

292
### Configuration Files
293

294
Generate configuration files for deployment:
295

296
```handlebars
297
{{!-- docker-compose.yml.hbs --}}
298
version: '3.8'
299
services:
300
  {{#each nodes}}
301
  {{this.unique-id}}:
302
    image: {{this.name}}:latest
303
    ports:
304
      {{#each this.interfaces}}
305
      - "{{this.port}}:{{this.port}}"
306
      {{/each}}
307
  {{/each}}
308
```
309

310
### Documentation
311

312
Generate architecture documentation:
313

314
```handlebars
315
{{!-- README.md.hbs --}}
316
# Architecture Documentation
317

318
## Services
319

320
{{#each nodes}}
321
### {{this.name}}
322

323
- **Type:** {{this.node-type}}
324
- **ID:** {{this.unique-id}}
325
{{#if this.description}}
326
- **Description:** {{this.description}}
327
{{/if}}
328

329
#### Interfaces
330
{{#each this.interfaces}}
331
- {{this.protocol}} on {{this.host}}:{{this.port}}
332
{{/each}}
333
{{/each}}
334
```
335

336
### Infrastructure as Code
337

338
Generate Terraform or CloudFormation templates:
339

340
```handlebars
341
{{!-- main.tf.hbs --}}
342
{{#each nodes}}
343
{{#if (eq this.node-type "database")}}
344
resource "aws_db_instance" "{{this.unique-id}}" {
345
  identifier = "{{this.unique-id}}"
346
  engine     = "{{this.metadata.engine}}"
347
  {{#each this.interfaces}}
348
  port       = {{this.port}}
349
  {{/each}}
350
}
351
{{/if}}
352
{{/each}}
353
```
354

355
## Error Handling
356

357
### Common Errors
358

359
**Multiple Template Options:**
360
```
361
❌ Please specify exactly one of --template, --template-dir, or --bundle
362
```
363
**Solution:** Use only one template source option.
364

365
**Missing Required Options:**
366
```
367
error: required option '-a, --architecture <path>' not specified
368
```
369
**Solution:** Provide required architecture and output options.
370

371
**Architecture File Not Found:**
372
```
373
Error: ENOENT: no such file or directory
374
```
375
**Solution:** Verify architecture file path is correct.
376

377
**Template Not Found:**
378
```
379
Error: Template file not found
380
```
381
**Solution:** Verify template path is correct and file exists.
382

383
**Invalid URL Mapping File:**
384
```
385
Error reading url to local file mapping file
386
```
387
**Solution:** Verify mapping file is valid JSON with correct format.
388

389
**Template Syntax Error:**
390
```
391
Error: Parse error on line X
392
```
393
**Solution:** Check Handlebars template syntax for errors.
394

395
## Integration with Other Commands
396

397
Template generation is typically used after architecture creation and validation:
398

399
```bash
400
# Step 1: Generate architecture from pattern
401
calm generate -p pattern.json -o architecture.json
402

403
# Step 2: Edit and validate architecture
404
calm validate -a architecture.json -p pattern.json
405

406
# Step 3: Generate code/configuration from architecture
407
calm template -a architecture.json -b ./code-gen-bundle -o ./src
408

409
# Step 4: Use generated code in project
410
npm install
411
npm run build
412
```
413

414
## Advanced Examples
415

416
### Multi-Output Bundle
417

418
Create a template bundle that generates multiple files:
419

420
**index.json:**
421
```json
422
{
423
  "name": "microservices-generator",
424
  "version": "1.0.0",
425
  "templates": [
426
    {
427
      "input": "service.hbs",
428
      "output": "src/services/{{unique-id}}.ts"
429
    },
430
    {
431
      "input": "dockerfile.hbs",
432
      "output": "docker/{{unique-id}}/Dockerfile"
433
    }
434
  ]
435
}
436
```
437

438
### Conditional Generation
439

440
Use conditionals to generate different outputs based on architecture content:
441

442
```handlebars
443
{{#each nodes}}
444
{{#if (eq this.node-type "database")}}
445
  {{> database-config this}}
446
{{else if (eq this.node-type "service")}}
447
  {{> service-config this}}
448
{{else}}
449
  {{> default-config this}}
450
{{/if}}
451
{{/each}}
452
```
453

454
### Custom Transformers
455

456
Template bundles can include custom transformers to pre-process the CALM model:
457

458
```typescript
459
// transformer.ts
460
export class CustomTransformer {
461
  transform(architecture: any): any {
462
    // Transform architecture structure for templates
463
    return {
464
      ...architecture,
465
      serviceNodes: architecture.nodes.filter(n => n['node-type'] === 'service'),
466
      databaseNodes: architecture.nodes.filter(n => n['node-type'] === 'database')
467
    };
468
  }
469
}
470
```
471

472
## Performance Considerations
473

474
### Large Architectures
475

476
For architectures with many nodes/relationships:
477
- Use template fragments and partials
478
- Avoid nested loops where possible
479
- Consider pre-filtering data in transformers
480

481
### Output Directory
482

483
- Use `--clear-output-directory` for clean slate generation
484
- Without flag, only modified files are updated (faster for incremental changes)
485

486
### Caching
487

488
The TemplateProcessor from `@finos/calm-shared` may cache:
489
- Parsed templates
490
- Loaded architecture
491
- URL mappings
492

493
Subsequent runs with same inputs are faster.
494

495
## Debugging
496

497
### Verbose Mode
498

499
Enable verbose logging to debug template processing:
500

501
```bash
502
calm template -a architecture.json -b ./bundle -o ./output -v
503
```
504

505
Shows:
506
- Template loading
507
- Architecture parsing
508
- URL mapping resolution
509
- File writing operations
510

511
### Template Testing
512

513
Test templates with minimal architectures:
514

515
```json
516
{
517
  "$schema": "https://calm.finos.org/schemas/calm-v1.json",
518
  "nodes": [
519
    {
520
      "unique-id": "test-node",
521
      "node-type": "service",
522
      "name": "Test Service"
523
    }
524
  ]
525
}
526
```
527

528
### Output Inspection
529

530
Review generated files to verify template logic:
531

532
```bash
533
calm template -a test-arch.json -t test-template.hbs -o test-output.txt
534
cat test-output.txt
535
```
536