Generate Command

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

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.

Capabilities

Generate Command

Generates a CALM architecture from a pattern file by prompting the user to select from pattern-defined options.

/**
 * Generate an architecture from a CALM pattern file
 * @command calm generate [options]
 */
interface GenerateCommandOptions {
  /** Path to pattern file (file path or CalmHub URL)
   * CLI flags: -p, --pattern <file>
   * Required: yes
   */
  pattern: string;

  /** Output path for generated architecture
   * CLI flags: -o, --output <file>
   * Default: "architecture.json"
   */
  output?: string;

  /** Path to directory containing meta schemas
   * CLI flags: -s, --schema-directory <path>
   */
  schemaDirectory?: string;

  /** URL to CALMHub instance for remote pattern/schema loading
   * CLI flags: -c, --calm-hub-url <url>
   */
  calmHubUrl?: string;

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

Usage Examples:

# Basic usage with local pattern file
calm generate -p pattern.json

# Specify custom output location
calm generate -p pattern.json -o my-architecture.json

# Use pattern from CALMHub URL
calm generate -p https://calmhub.example.com/patterns/api-gateway.json

# Use pattern with custom schema directory
calm generate -p pattern.json -s ./custom-schemas

# Enable verbose logging for debugging
calm generate -p pattern.json -v

Pattern Options

Patterns can define options that users select during generation:

OneOf Options

User must select exactly one choice from the available options:

{
  "oneOf": [
    { "description": "REST API", "nodes": [...] },
    { "description": "GraphQL API", "nodes": [...] }
  ]
}

The CLI presents these as a single-selection list prompt.

AnyOf Options

User can select zero or more choices from the available options:

{
  "anyOf": [
    { "description": "Authentication", "nodes": [...] },
    { "description": "Rate Limiting", "nodes": [...] },
    { "description": "Caching", "nodes": [...] }
  ]
}

The CLI presents these as a multi-selection checkbox prompt.

Configuration

CALMHub Integration

When using CALMHub for remote pattern loading:

1. Via Command-Line Option:

calm generate -p my-pattern.json -c https://calmhub.example.com

2. Via User Configuration File (~/.calm.json):

{
  "calmHubUrl": "https://calmhub.example.com"
}

The command-line option takes precedence over the configuration file setting.

Schema Directory

Patterns are validated against CALM meta schemas. You can specify a custom schema directory:

calm generate -p pattern.json -s ./path/to/schemas

If not specified, the default schema directory from @finos/calm-shared is used.

Output

The generate command creates a JSON file containing the generated CALM architecture. The architecture includes:

• All nodes, relationships, and other components defined in the pattern
• Values based on the user's selected options
• Placeholder values (marked with -1 for numbers, "PLACEHOLDER" for strings) that need to be filled in

Example output structure:

{
  "$schema": "https://calm.finos.org/schemas/calm-v1.json",
  "nodes": [
    {
      "unique-id": "api-gateway",
      "node-type": "system",
      "name": "API Gateway",
      "interfaces": [
        {
          "unique-id": "rest-api",
          "host": "PLACEHOLDER",
          "port": -1
        }
      ]
    }
  ]
}

Users should replace placeholder values with actual values for their architecture.

Workflow

1. Pattern Loading:

   • Load pattern from file path or URL
   • Validate pattern structure
   • Extract options from pattern

2. User Interaction:

   • Present options to user via interactive prompts
   • Collect user selections (oneOf as radio, anyOf as checkboxes)
   • Validate selections against pattern constraints

3. Architecture Generation:

   • Build schema directory for validation
   • Generate architecture based on pattern and selections
   • Apply selected options to architecture structure

4. Output:

   • Write generated architecture to specified output file
   • Report any errors or warnings

Error Handling

Common errors and their meanings:

Pattern Loading Errors

Error: Failed to load pattern from <path>

Cause: Pattern file not found or URL unreachable

Solution: Verify pattern path/URL is correct and accessible

Schema Validation Errors

Error: Pattern validation failed

Cause: Pattern does not conform to CALM pattern schema

Solution: Validate pattern structure against CALM pattern schema

Option Selection Errors

Error: The choice of [<value>] is not a valid choice in the pattern

Cause: Internal error where invalid option was selected

Solution: This should not occur in normal usage; report as a bug

File Write Errors

Error: Failed to write output file

Cause: Permission denied or invalid output path

Solution: Verify output directory exists and is writable

Integration with Other Commands

The generate command is typically the first step in a CALM workflow:

1. Generate → Creates architecture shell from pattern
2. Edit → User fills in placeholder values
3. Validate → Verify architecture conforms to pattern
4. Template/Docify → Generate code or documentation from architecture

Example workflow:

# Step 1: Generate architecture from pattern
calm generate -p api-gateway-pattern.json -o my-api.json

# Step 2: Edit my-api.json to replace placeholders
# (manual editing)

# Step 3: Validate the completed architecture
calm validate -a my-api.json -p api-gateway-pattern.json

# Step 4: Generate documentation
calm docify -a my-api.json -o ./docs

Types

// Pattern option types from @finos/calm-shared
interface CalmOption {
  optionType: 'oneOf' | 'anyOf';
  prompt: string;
  choices: CalmChoice[];
}

interface CalmChoice {
  description: string;
  nodes?: any[];
  relationships?: any[];
  // ... other CALM components
}

// Document loader configuration
interface DocumentLoaderOptions {
  calmHubUrl?: string;
  schemaDirectoryPath?: string;
  debug: boolean;
}