Morphir Go

A Go implementation of the Morphir tooling ecosystem. Morphir is a technology-agnostic intermediate representation (IR) for business logic and data models, enabling code generation, documentation, and analysis across multiple target platforms.

This project provides a CLI application built with Cobra and Bubbletea, along with library modules for working with Morphir IR.

Installation

Option 1: Download Binary (Recommended)

Download the latest release for your platform from GitHub Releases:

• Linux (amd64/arm64): morphir_X.Y.Z_Linux_{x86_64,arm64}.tar.gz
• macOS (amd64/arm64): morphir_X.Y.Z_Darwin_{x86_64,arm64}.tar.gz
• Windows (amd64): morphir_X.Y.Z_Windows_x86_64.zip

Extract and move to your PATH:

# Linux/macOS
tar -xzf morphir_*.tar.gz
sudo mv morphir /usr/local/bin/

# Windows (PowerShell)
Expand-Archive morphir_*.zip
Move-Item morphir.exe $env:USERPROFILE\bin\

Option 2: Install via Go

go install github.com/finos/morphir-go/cmd/morphir@latest

Option 3: Build from Source

Prerequisites:

• Go 1.25.5 or later (download)
• just - A command runner for build orchestration (install)
• PowerShell (Windows only) - For running build scripts on Windows (install)

Build steps:

# Clone the repository
git clone https://github.com/finos/morphir-go.git
cd morphir-go

# Build the CLI application
just build

# The binary will be in bin/morphir

Install to system:

# Build and install to $GOPATH/bin or $GOBIN
just install

Verify Installation

morphir --version

Usage

Running the CLI

# Launch the interactive TUI
morphir

# Get help
morphir help

# Get help for a specific command
morphir help workspace

# Initialize a new workspace
morphir workspace init [path]

# View configuration
morphir config show

# Show configuration file locations
morphir config path

Configuration

Morphir uses a layered configuration system. Configuration is loaded from multiple sources in priority order, with higher-priority sources overriding lower ones.

Quick Start

# Initialize a workspace (creates morphir.toml)
morphir workspace init

# View the resolved configuration
morphir config show

# See which config files are loaded
morphir config path

Configuration Sources

Priority	Source	Description
6 (highest)	Environment	MORPHIR_* variables
5	User override	.morphir/morphir.user.toml (gitignored)
4	Project	morphir.toml or .morphir/morphir.toml
3	Global	~/.config/morphir/morphir.toml
2	System	/etc/morphir/morphir.toml
1 (lowest)	Defaults	Built-in defaults

Example Configuration

[morphir]
version = "^3.0.0"

[codegen]
targets = ["go", "typescript"]

[logging]
level = "info"
format = "text"

Environment Variables

Override any setting with MORPHIR_ prefix:

export MORPHIR_LOGGING_LEVEL=debug
export MORPHIR_CACHE_ENABLED=false

For complete documentation, see docs/configuration.md.

Module Structure

This is a Go monorepo with multiple modules:

• cmd/morphir/ - CLI application (Cobra + Bubbletea)
• pkg/config/ - Layered configuration system
• pkg/models/ - Morphir IR model types and data structures
• pkg/tooling/ - Utilities and tools for working with Morphir IR
  • pkg/tooling/workspace/ - Workspace discovery and initialization
• pkg/sdk/ - SDK for building applications that work with Morphir IR
• pkg/pipeline/ - Processing pipelines for Morphir IR transformations

Each package is a separate Go module, managed via go.work for seamless development.

Development Workflow

Build Orchestration with Just

We use just for build orchestration. Common commands:

# List all available commands
just

# Set up development environment (first time setup)
just setup

# Build the CLI application
just build

# Run tests across all modules
just test

# Format all Go code
just fmt

# Run linters (requires golangci-lint)
just lint

# Download dependencies for all modules
just deps

# Run go mod tidy for all modules
just mod-tidy

# Clean build artifacts
just clean

# Verify all modules build successfully
just verify

# Run CI checks (format, build, test, lint)
just ci-check

Local Development and Testing

For local development, we recommend using morphir-dev to distinguish your development version from any installed morphir CLI:

# Build the development version
just build-dev

# The binary will be in bin/morphir-dev

# Run the development version directly
just run-dev

# Or run it manually
./bin/morphir-dev

# Test specific commands
./bin/morphir-dev help
./bin/morphir-dev workspace init

# Launch the TUI
./bin/morphir-dev

# Install morphir-dev to your system (makes it available in PATH)
just install-dev

# After installation, you can use morphir-dev from anywhere
morphir-dev help

Why use morphir-dev?

• Keeps your development version separate from any installed morphir CLI
• Allows you to test changes without affecting your installed version
• Makes it clear which version you're running during development
• Enables side-by-side comparison with the installed version
• Can be installed system-wide for easy access during development

Development Setup

1. Clone the repository

   git clone https://github.com/finos/morphir-go.git
   cd morphir-go

2. Set up the development environment

   just setup

   This command will:

   • Sync Go workspace modules
   • Install npm dependencies (for git hooks)
   • Set up pre-push hooks that run formatting, linting, and tests

   Prerequisites for just setup:

   • Node.js (v16+) - for git hooks via Husky
   • npm - comes with Node.js

3. Build the project

   # For development, use build-dev
   just build-dev
   
   # Or for standard build
   just build

4. Run tests

   just test

5. Test your changes

   # Build and run the development version
   just run-dev
   
   # Or test specific commands
   ./bin/morphir-dev help

Git Hooks

This project uses Husky for git hooks. After running just setup, the following hooks are installed:

• pre-push: Runs before each push to verify:
  • Go code formatting (gofmt)
  • Linting (golangci-lint if installed)
  • go vet checks
  • All tests pass

If any check fails, the push is aborted. This ensures code quality is maintained before changes reach the remote repository.

Note: If you don't have Node.js installed, git hooks won't be enabled, but you can still contribute - CI will catch any issues.

Go Workspace

This project uses Go workspaces (go.work) to manage the multi-module monorepo. The workspace file includes all modules, allowing seamless cross-module development without requiring local replacements.

Scripts Directory

The scripts/ directory contains reusable scripts used in build, CI, and development workflows. These scripts are referenced from the Justfile and can also be used directly:

• scripts/mod-tidy.sh / scripts/mod-tidy.ps1 - Runs go mod tidy for all modules
• scripts/install-dev.sh / scripts/install-dev.ps1 - Installs morphir-dev to Go bin directory
• scripts/verify.sh / scripts/verify.ps1 - Verifies all modules build successfully

Cross-Platform Support:

• All scripts have both bash (.sh) and PowerShell (.ps1) versions
• The Justfile automatically detects the platform and uses the appropriate script
• On Windows, PowerShell scripts are used when PowerShell is available
• On Unix-like systems (Linux, macOS), bash scripts are used

Scripts are used in the Justfile for complex operations and can be invoked directly when needed.

Development Principles

This project follows functional programming principles and practices. For detailed guidance on:

• Functional programming patterns
• Test-driven development (TDD)
• Behavior-driven development (BDD)
• Code organization principles
• Morphir design principles

See AGENTS.md for comprehensive development guidelines.

Roadmap

• Initial monorepo structure
• CLI application with Cobra and Bubbletea
• Basic command structure (help, workspace)
• Cross-platform support (Linux, macOS, Windows)
• Automated releases with GoReleaser
• Workspace initialization implementation
• Morphir IR model support
• Tooling utilities
• SDK implementation
• Pipeline processing

Releasing (for Maintainers)

This project uses GoReleaser with GitHub Actions for automated releases.

Release Process

1. Update CHANGELOG.md

   # Move [Unreleased] changes to new version section
   # Add release date: ## [X.Y.Z] - YYYY-MM-DD
   # Create new [Unreleased] section

2. Commit and tag

   git add CHANGELOG.md
   git commit -m "chore: prepare release vX.Y.Z"
   git tag -a vX.Y.Z -m "Release X.Y.Z"
   git push origin main
   git push origin vX.Y.Z

3. GitHub Actions will automatically:

   • Build binaries for all platforms (Linux, macOS, Windows)
   • Build for all architectures (amd64, arm64)
   • Generate checksums
   • Create GitHub Release with artifacts
   • Generate release notes from commits

Local Testing

Before creating a release, test locally:

# Validate GoReleaser config
just goreleaser-check

# Build snapshot (no publish)
just release-snapshot

# Full dry-run
just release-test

Versioning

This project follows Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Use Conventional Commits for better changelogs:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• chore: - Maintenance
• feat!: or fix!: - Breaking change

See AGENTS.md for detailed release documentation.

Contributing

For any questions, bugs or feature requests please open an issue.

To submit a contribution:

1. Fork it (https://github.com/finos/morphir-go/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Read our contribution guidelines and Community Code of Conduct
4. Commit your changes (git commit -am 'Add some fooBar')
5. Push to the branch (git push origin feature/fooBar)
6. Create a new Pull Request

NOTE: Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool (or EasyCLA). Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.

Need an ICLA? Unsure if you are covered under an existing CCLA? Email [email protected]

License

Copyright 2022 FINOS

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0