tessl/npm-finos--calm-cli

A comprehensive command-line interface for working with the Common Architecture Language Model (CALM)

Overview

Eval results

Files

Docify Command

Name: tessl/npm-finos--calm-cli
Author: tessl

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

The docify command generates documentation websites from CALM models. It provides a built-in website generator or supports custom templates, transforming CALM architectures into human-readable documentation with navigation, styling, and architecture visualizations.

Capabilities

Docify Command

Generate documentation websites from CALM models.

/**
 * Generate a documentation website from a CALM model
 * @command calm docify [options]
 */
interface DocifyCommandOptions {
  /** Path to CALM architecture JSON file
   * CLI flags: -a, --architecture <file>
   * Required: yes
   */
  architecture: string;

  /** Path to output directory
   * CLI flags: -o, --output <file>
   * Required: yes
   */
  output: string;

  /** Delete output directory contents before processing
   * CLI flags: --clear-output-directory
   * Default: false
   */
  clearOutputDirectory?: boolean;

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

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

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

  /** Enable verbose logging
   * CLI flags: -v, --verbose
   * Default: false
   */
  verbose?: boolean;
}

Requirements:

At most one of template or templateDir can be specified
Cannot use both template options simultaneously

Usage Examples:

# Generate website using built-in template
calm docify -a architecture.json -o ./docs

# Generate with custom single template
calm docify -a architecture.json -o ./docs -t ./custom-template.md

# Generate with custom template directory
calm docify -a architecture.json -o ./docs -d ./custom-templates

# Clear output directory before generation
calm docify -a architecture.json -o ./docs --clear-output-directory

# With URL-to-local-file mapping
calm docify -a architecture.json -o ./docs -u ./url-mappings.json

# With verbose logging
calm docify -a architecture.json -o ./docs -v

Documentation Modes

Website Mode (Default)

When no template is specified, docify uses a built-in template bundle to generate a complete documentation website:

calm docify -a architecture.json -o ./docs

Generated Website Includes:

Homepage with architecture overview
Node listings with details
Relationship diagrams
Interface documentation
Navigation menu
Responsive styling
Search functionality (if supported)

Custom Template Mode

Use your own templates for custom documentation formats:

# Single template
calm docify -a architecture.json -o ./docs -t ./template.md

# Template directory
calm docify -a architecture.json -o ./docs -d ./templates

Generated Website Structure

Using the default website mode:

docs/
├── index.html           # Homepage with overview
├── nodes/
│   ├── index.html      # Node listing
│   └── [node-id].html  # Individual node pages
├── relationships/
│   ├── index.html      # Relationship listing
│   └── [rel-id].html   # Individual relationship pages
├── assets/
│   ├── css/
│   │   └── styles.css  # Website styling
│   └── js/
│       └── main.js     # Interactive features
└── images/
    └── diagrams/       # Generated diagrams

URL-to-Local-File Mapping

Map external URL references to local files for offline documentation generation:

Mapping File Format

{
  "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json",
  "https://calm.finos.org/patterns/api-gateway": "patterns/api-gateway.json"
}

Usage:

calm docify \
  -a architecture.json \
  -o ./docs \
  -u ./url-mappings.json

When referenced URLs are encountered in the architecture, content is loaded from local files instead of fetching remotely.

Output Behavior

Default Behavior

Output directory is created if it doesn't exist
Existing files are modified if they match generated output names
Unrelated files remain unchanged

Clear Output Directory

With --clear-output-directory flag:

calm docify -a architecture.json -o ./docs --clear-output-directory

Warning: Completely deletes all files and subdirectories in the output directory before generation.

Template Customization

Custom Single Template

Create a custom Markdown or Handlebars template:

custom-docs.md:

# {{name}} Architecture

## Overview

This architecture contains {{nodes.length}} nodes and {{relationships.length}} relationships.

## Nodes

{{#each nodes}}
### {{this.name}}

- **Type:** {{this.node-type}}
- **ID:** {{this.unique-id}}
{{#if this.description}}
- **Description:** {{this.description}}
{{/if}}

{{/each}}

Usage:

calm docify -a architecture.json -o ./docs -t ./custom-docs.md

Custom Template Directory

Create a directory with multiple templates:

templates/
├── index.md.hbs        # Homepage
├── nodes.md.hbs        # Node documentation
├── relationships.md.hbs # Relationship documentation
└── README.md.hbs       # Additional documentation

Usage:

calm docify -a architecture.json -o ./docs -d ./templates

Each template generates a corresponding output file.

Docify Modes

The docify command uses different modes from @finos/calm-shared:

WEBSITE Mode (Default)

docifyMode: 'WEBSITE'
templateProcessingMode: 'bundle'

Uses built-in website template bundle for complete documentation site generation.

USER_PROVIDED Mode

docifyMode: 'USER_PROVIDED'
templateProcessingMode: 'template' | 'template-directory'

Uses custom user-provided templates for documentation generation.

Common Use Cases

Architecture Documentation

Generate comprehensive architecture documentation:

calm docify -a architecture.json -o ./docs

Share the ./docs directory via:

Static site hosting (GitHub Pages, Netlify, etc.)
Internal wiki or documentation platform
PDF generation tools

API Documentation

Create API documentation from CALM models with interface details:

api-docs.md.hbs:

# API Documentation

{{#each nodes}}
{{#if (eq this.node-type "service")}}
## {{this.name}} API

{{#each this.interfaces}}
### {{this.protocol}} Interface

- **Endpoint:** {{this.host}}:{{this.port}}
{{#if this.path}}
- **Base Path:** {{this.path}}
{{/if}}

{{/each}}
{{/if}}
{{/each}}

System Diagrams

Generate documentation with embedded diagrams:

# System Architecture

## Component Diagram

```mermaid
graph TD
{{#each nodes}}
  {{this.unique-id}}[{{this.name}}]
{{/each}}

{{#each relationships}}
  {{this.relationship-type.connects.source.node}} -->|{{this.relationship-type.type}}| {{this.relationship-type.connects.destination.node}}
{{/each}}
\```

Deployment Documentation

Document deployment architecture:

# Deployment Architecture

{{#each nodes}}
## {{this.name}}

### Deployment Details

{{#if this.metadata.region}}
- **Region:** {{this.metadata.region}}
{{/if}}
{{#if this.metadata.availability-zone}}
- **Availability Zone:** {{this.metadata.availability-zone}}
{{/if}}

### Network Configuration

{{#each this.interfaces}}
- **Protocol:** {{this.protocol}}
- **Port:** {{this.port}}
{{/each}}

{{/each}}

Error Handling

Common Errors

Multiple Template Options:

❌ Please specify only one of --template or --template-dir

Solution: Use at most one template option.

Missing Required Options:

error: required option '-a, --architecture <path>' not specified

Solution: Provide required architecture and output options.

Architecture File Not Found:

Error: ENOENT: no such file or directory

Solution: Verify architecture file path is correct.

Template Not Found:

Error: Template file not found

Solution: Verify template path is correct.

Invalid URL Mapping:

Error reading url to local file mapping file

Solution: Verify mapping file is valid JSON.

Integration with Other Commands

Docify is typically used after architecture creation and validation:

# Step 1: Generate architecture
calm generate -p pattern.json -o architecture.json

# Step 2: Validate architecture
calm validate -a architecture.json -p pattern.json

# Step 3: Generate documentation
calm docify -a architecture.json -o ./docs

# Step 4: Serve documentation locally
cd docs
python -m http.server 8000
# Open http://localhost:8000

Hosting Documentation

Static Site Hosting

GitHub Pages

# Generate docs in docs/ directory
calm docify -a architecture.json -o ./docs

# Commit and push
git add docs
git commit -m "Update architecture documentation"
git push

# Enable GitHub Pages in repository settings (source: /docs folder)

Netlify

# Generate docs
calm docify -a architecture.json -o ./docs

# Deploy to Netlify
netlify deploy --dir=docs --prod

AWS S3

# Generate docs
calm docify -a architecture.json -o ./docs

# Deploy to S3
aws s3 sync ./docs s3://my-architecture-docs --delete

Local Serving

# Python
cd docs && python -m http.server 8000

# Node.js (with http-server)
npx http-server docs -p 8000

# PHP
cd docs && php -S localhost:8000

Advanced Features

Embedding External Content

Reference external flows, patterns, or documentation:

{
  "nodes": [{
    "unique-id": "service-1",
    "flows": ["https://calm.finos.org/flows/authentication.json"]
  }]
}

With URL mapping, these are embedded in the documentation.

Multi-Architecture Documentation

Document multiple related architectures:

# Generate docs for each architecture
calm docify -a prod-architecture.json -o ./docs/prod
calm docify -a staging-architecture.json -o ./docs/staging
calm docify -a dev-architecture.json -o ./docs/dev

# Create index page linking to each

Version Control

Track documentation changes alongside architecture:

# Generate docs
calm docify -a architecture.json -o ./docs

# Commit architecture and docs together
git add architecture.json docs/
git commit -m "Update architecture and regenerate docs"

CI/CD Integration

Automatically regenerate documentation on architecture changes:

GitHub Actions Example:

name: Generate Documentation
on:
  push:
    paths:
      - 'architecture.json'

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g @finos/calm-cli
      - run: calm docify -a architecture.json -o ./docs
      - run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add docs
          git commit -m "Regenerate documentation"
          git push

Debugging

Verbose Mode

Enable verbose logging for debugging:

calm docify -a architecture.json -o ./docs -v

Shows:

Template loading
Architecture parsing
File generation
URL mapping resolution

Output Inspection

Review generated files:

calm docify -a architecture.json -o ./docs
ls -la ./docs
cat ./docs/index.html

Template Testing

Test templates with minimal architectures:

{
  "$schema": "https://calm.finos.org/schemas/calm-v1.json",
  "nodes": [{
    "unique-id": "test",
    "node-type": "service",
    "name": "Test Service"
  }]
}

Performance Considerations

Large Architectures

For architectures with many nodes:

Use pagination in custom templates
Generate index pages with summaries
Create separate pages for detailed views

Asset Generation

Documentation generation may include:

Diagram generation
Asset copying
CSS/JS bundling

This can take time for large architectures with many diagrams.

Incremental Updates

Without --clear-output-directory, only changed files are regenerated (faster for small updates).

Styling and Customization

Custom CSS

When using custom templates, include your own styling:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="custom-styles.css">
</head>
<body>
  <!-- Generated content -->
</body>
</html>

Themes

Create reusable template bundles with different themes:

themes/
├── modern/
│   ├── index.json
│   ├── templates/
│   └── assets/
└── classic/
    ├── index.json
    ├── templates/
    └── assets/

Use different custom template directories:

calm docify -a architecture.json -o ./docs-modern -d themes/modern
calm docify -a architecture.json -o ./docs-classic -d themes/classic

Best Practices

Version Documentation: Commit generated docs alongside architecture files
Automate Generation: Use CI/CD to regenerate docs on architecture changes
Use Clear Structure: Organize documentation with logical navigation
Include Examples: Add usage examples and context to generated docs
Test Output: Review generated documentation before publishing
Maintain Templates: Keep custom templates updated with CALM schema changes
Use URL Mappings: Map external references for offline documentation

Install with Tessl CLI

npx tessl i tessl/npm-finos--calm-cli

docs

copilot-chatmode-command.md

tessl/npm-finos--calm-cli

docify-command.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Docify Command

Capabilities

Docify Command

Documentation Modes

Website Mode (Default)

Custom Template Mode

Generated Website Structure

URL-to-Local-File Mapping

Mapping File Format

Output Behavior

Default Behavior

Clear Output Directory

Template Customization

Custom Single Template

Custom Template Directory

Docify Modes

WEBSITE Mode (Default)

USER_PROVIDED Mode

Common Use Cases

Architecture Documentation

API Documentation

System Diagrams

Deployment Documentation

Error Handling

Common Errors

Integration with Other Commands

Hosting Documentation

Static Site Hosting

GitHub Pages

Netlify

AWS S3

Local Serving

Advanced Features

Embedding External Content

Multi-Architecture Documentation

Version Control

CI/CD Integration

Debugging

Verbose Mode

Output Inspection

Template Testing

Performance Considerations

Large Architectures

Asset Generation

Incremental Updates

Styling and Customization

Custom CSS

Themes

Best Practices

docify-command.mddocs/