🫏 MAIASS (Node.js Edition)

Modular AI-Augmented Semantic Scribe - Cross-platform Node.js implementation

---

MAIASS is an intelligent Git workflow automation tool that streamlines version management, changelog generation, and deployment processes with AI-powered commit message suggestions. This Node.js implementation provides cross-platform compatibility and self-contained binary distribution.

🚀 Quick Start

Installation

Cross-Platform Binaries (Recommended):

# Download and install for your platform
curl -L https://github.com/vsmash/maiass/releases/latest/download/maiass-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o maiass
chmod +x maiass
./maiass --version

From Source:

git clone https://github.com/vsmash/nodemaiass.git
cd nodemaiass && npm install && npm link

Basic Usage

# Complete workflow with patch version bump
maiass

# Specific version bumps
maiass minor    # 1.2.3 → 1.3.0
maiass major    # 1.2.3 → 2.0.0
maiass 2.1.0    # Set specific version

# Commit only (skip version management)
maiass --commits-only

# Preview changes without applying
maiass --dry-run

AI-Powered Commit Messages

# Enable AI features
maiass config set maiass_token "your_api_key"
maiass config set ai_mode "ask" (or "always" or "off")

# MAIASS will now suggest intelligent commit messages
maiass

✨ Key Features- 🤖 AI-Powered Commit Messages: AI integration for intelligent commit suggestions- 📋 Dual Changelog System: User-facing and developer-facing changelogs- 🔄 Complete Git Workflow: Branch validation, commits, merges, and versioning- 🏷️ Smart Version Management: Multiple version file support with semantic versioning- 🌍 Cross-Platform: Self-contained binaries for macOS, Linux, and Windows- ⚙️ Zero Configuration: Works out of the box with sensible defaults- 🎯 JIRA Integration: Automatic ticket detection from branch names

� Documentation

| Topic | Description | |-------|-------------| | Installation Guide | Detailed installation instructions and binaries | | Configuration | Environment variables and project setup | | Workflow Guide | Complete workflow documentation | | Commands Reference | All available commands and options | | Cross-Platform Guide | Platform-specific notes and compatibility | | Development | Contributing and development setup |

🔧 Supported Technologies

Version File Formats- package.json (Node.js/npm projects)- composer.json (PHP/Composer projects)- VERSION files (plain text)- Git tags only (for projects without version files)

Git Platforms- GitHub (public and private repositories)- Bitbucket (Cloud and Server)- Any Git host (core features work universally)

AI Models- GPT-4o (recommended for complex projects)- GPT-4 (balanced performance and cost)- GPT-3.5-turbo (fast and economical)

🌍 Platform Support

| Platform | Binary Available | Self-Contained | |----------|------------------|----------------| | macOS Intel | ✅ maiass-macos-intel | ✅ Node.js included | | macOS Apple Silicon | ✅ maiass-macos-arm64 | ✅ Node.js included | | Linux x64 | ✅ maiass-linux-x64 | ✅ Node.js included | | Linux ARM64 | ✅ maiass-linux-arm64 | ✅ Node.js included | | Windows x64 | ✅ maiass-windows-x64.exe | ✅ Node.js included | | Windows ARM64 | ✅ maiass-windows-arm64.exe | ✅ Node.js included |

🔄 Workflow Overview

MAIASS orchestrates a 4-phase intelligent workflow:

1. Branch Detection & Validation - Validates current branch and workflow requirements
2. Commit Workflow - AI-powered commit messages with JIRA integration
3. Merge Management - Handles branch merging and conflict resolution
4. Version & Changelog - Semantic versioning with dual changelog generation

⚙️ Quick Configuration

# Enable AI features (global)
maiass config set --global maiass_token "your_api_key"
maiass config set --global ai_mode "ask"

# Project-specific branch override
maiass config set mainbranch "main"

# View current configuration
maiass config list

🎯 What Makes This Special?

Intelligent Automation- Smart Version Detection: Automatically finds and updates version files- Context-Aware AI: Analyzes code changes for meaningful commit messages- Dual Changelog System: Clean user-facing + detailed developer changelogs

Developer Experience- Self-Contained Binaries: No Node.js installation required- Cross-Platform Compatibility: Consistent behavior across all platforms- Zero Configuration: Works immediately with sensible defaults

Enterprise Ready- Security First: API keys never stored in repositories- CI/CD Integration: Perfect for automated deployment pipelines- GPL-3.0 Licensed: Free and open source software

🔗 Related Projects- MAIASS (Bash) - Original bash implementation- Homebrew Formula - Homebrew installation

🤝 Contributing

We welcome contributions! Whether it's:- 🐛 Bug reports and feature requests- 📖 Documentation improvements- 🔧 Code contributions and enhancements- 💡 Ideas for new features

See our Development Guide to get started.

📄 License

MAIASS is released under the GNU General Public License v3.0. Free and open source software.

🔗 Links- GitHub Repository- Issue Tracker- Releases- Original MAIASS---

Ready to streamline your Git workflow? Download MAIASS today and experience intelligent version management with AI-powered automation.

# Get the latest release
curl -L https://github.com/vsmash/maiass/releases/latest/download/maiass-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o maiass && chmod +x maiass
```---

**Made with ❤️ for developers who want better Git workflows**
maiass version [major|minor|patch|version]

# Configuration
maiass config list
maiass config get <key>
maiass config set <key> <value>

# Environment info
maiass env

# Git information
maiass git-info
maiass git              # Show git status and branch info

# Environment variables
maiass env              # Show current environment
maiass env --json       # Show environment as JSON

⚙️ Configuration

Quick Setup

1. Enable AI features (optional):

   # Set Maiass API key globally
   maiass config --global maiass_token=your_api_key_here

2. Project-specific settings (if needed):

   # Override branch names for projects using 'main'
   maiass config --project mainbranch=main

Configuration Files

MAIASS uses .env.maiass files for configuration:- Global: ~/.env.maiass (user-wide settings)- Project: ./.env.maiass (project-specific overrides)

Common Configuration Variables

# AI Integration
MAIASS_AI_TOKEN=your_api_key_here
MAIASS_AI_MODE=ask                    # ask, autosuggest, off
MAIASS_AI_MODEL=gpt-4                 # AI model to use

# Branch Configuration (only set if different from defaults)
MAIASS_MAINBRANCH=main                  # Default: main
MAIASS_DEVELOPBRANCH=develop              # Default: develop
MAIASS_STAGINGBRANCH=staging              # Default: staging

# Workflow Settings
MAIASS_DEBUG=true                         # Enable debug output
MAIASS_VERBOSITY=normal                   # brief, normal, verbose
MAIASS_AUTO_TAG_RELEASES=true             # Automatically tag releases (required for changelog)

# Changelog Configuration
MAIASS_CHANGELOG_PATH=CHANGELOG.md        # Main changelog file path
MAIASS_CHANGELOG_NAME=CHANGELOG.md        # Main changelog file name
MAIASS_CHANGELOG_INTERNAL_NAME.CHANGELOG_internal.md  # Internal changelog file name

🔄 Workflow Phases

MAIASS orchestrates a 4-phase workflow:

1. Branch Detection & Validation- Detects current branch and validates against workflow requirements- Auto-switches from main/staging to develop branch- Prompts for confirmation on release/main branches- Handles missing develop branch gracefully

2. Commit Workflow- Detects staged and unstaged changes- Offers AI-powered commit message suggestions- Supports multi-line commit messages- Prepends JIRA ticket numbers from branch names

3. Merge to Develop- Merges feature branches to develop for version management- Pulls latest changes from remote- Handles merge conflicts with clear error messages

4. Version Management- Detects version files (package.json, composer.json, etc.)- Bumps semantic versions (major.minor.patch)- Updates multiple version files simultaneously- Creates git tags for releases- Generates dual changelogs:

• CHANGELOG.md: Clean, user-facing format with JIRA tickets stripped
• .CHANGELOG_internal.md: Developer format with commit hashes, authors, and JIRA tickets- Smart commit range detection: Only includes commits since the last release tag- Version replacement logic: Replaces same-day patch versions instead of duplicating entries

📝 Changelog System

MAIASS automatically generates two types of changelogs during version management:

Main Changelog (CHANGELOG.md)

User-facing format with clean, readable entries:

## 0.5.6
24 July 2025- Update Maiass Pipeline functionality
	- feat: imported path package in maiass-pipeline
	- docs: added comment about commit message formatting- Updated commit message filtering for maiass-pipeline
	- feat: added code to clean up commit messages
	- fix: removed empty lines and trailing newlines from each commit

Internal Changelog (CHANGELOG_internal.md)

Developer-facing format with commit hashes, authors, and JIRA tickets:

## 0.5.6
Thursday, 24 July 2025- d7ddba9 VEL-405 Update Maiass Pipeline functionality (Developer Name)- 5ea6d03 VEL-405 Updated commit message filtering for maiass-pipeline (Developer Name)

Changelog Features- Smart commit detection: Only includes commits since the last release tag- Automatic filtering: Excludes merge commits, version bumps, and irrelevant entries- JIRA integration: Strips JIRA tickets from main changelog, preserves in internal- Version replacement: Same-day patch versions replace previous entries instead of duplicating- Clean formatting: No double bullets or unwanted blank lines

🎨 Examples

Complete Feature Development Workflow

# On feature branch: feature/USER-123-new-login

# 1. Complete workflow with minor version bump
maiass minor --tag

# This will:
# - Detect you're on a feature branch
# - Run commit workflow with AI suggestions
# - Merge to develop branch
# - Bump minor version (1.0.0 → 1.1.0)
# - Create git tag v1.1.0

Quick Commit Without Version Management

# Just commit changes without version bumping
maiass --commits-only --auto-stage

# With AI commit message
maiass commit

Safe Testing

# Preview what would happen without making changes
maiass --dry-run patch

# Check current version status
maiass version --current

🔧 Advanced Usage

Custom Version Files

# Configure custom version file
maiass config --project version_primary_file=VERSION.txt
maiass config --project version_primary_type=text

Multiple Version Files

# Update multiple files with same version
maiass config --project version_secondary_files="src/version.js,docs/VERSION"

AI Customization

# Different AI modes
maiass config --global ai_mode=autosuggest  # Auto-suggest without asking
maiass config --global ai_mode=off          # Disable AI

# Custom commit message style
maiass config --global ai_commit_message_style=conventional

🐛 Troubleshooting

Common Issues

"Not in a git repository"

# Ensure you're in a git repository
git status

"No version files detected"

# Check for supported version files
ls package.json composer.json VERSION

# Or configure custom version file
maiass config --project version_primary_file=your-version-file

"Failed to switch to develop branch"

# Create develop branch if it doesn't exist
git checkout -b develop

Debug Mode

# Enable verbose debugging
export MAIASS_DEBUG=true
maiass --dry-run

📚 Documentation- Configuration Guide- Workflow Guide- API Reference- Contributing

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments- Original MAIASS bash script by vsmash- OpenAI for AI-powered commit messages- Node.js and npm ecosystem---

Made with ❤️ by the MAIASS team