🫏 MAIASS (Node.js Edition)

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

![Node.js](https://nodejs.org/)
![License](LICENSE)
![Version](package.json)---

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

$3

Cross-Platform Binaries (Recommended):
``bash

`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:`bash git clone https://github.com/vsmash/nodemaiass.git cd nodemaiass && npm install && npm link`

`$3`

`bash

`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

$3

`bash

`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
$3
$3
$3
🌍 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`

`bash

`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?
$3
$3
$3
🔗 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.

`bash

`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 
maiass config set  
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
$3

1. Enable AI features (optional):`bash # Set Maiass API key globally maiass config --global maiass_token=your_api_key_here`

2. Project-specific settings (if needed):`bash # Override branch names for projects using 'main' maiass config --project mainbranch=main`

`$3`

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

`$3`

`bash

`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:
$3
$3
$3
$3

  -

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:
$3

User-facing format with clean, readable entries:

markdown
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


$3

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

markdown
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)


$3
🎨 Examples
$3

bash
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

$3

bash
Just commit changes without version bumping

maiass --commits-only --auto-stage
With AI commit message

maiass commit

$3

bash
Preview what would happen without making changes

maiass --dry-run patch
Check current version status

maiass version --current


🔧 Advanced Usage
$3

bash
Configure custom version file

maiass config --project version_primary_file=VERSION.txt
maiass config --project version_primary_type=text

$3

bash
Update multiple files with same version

maiass config --project version_secondary_files="src/version.js,docs/VERSION"

$3

bash
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
$3

"Not in a git repository"`bash

`Ensure you're in a git repository`


git status

"No version files detected"`bash

`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"`bash

`Create develop branch if it doesn't exist`


git checkout -b develop

$3

bash
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

🫏 MAIASS (Node.js Edition)

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

![Node.js](https://nodejs.org/)
![License](LICENSE)
![Version](package.json)---

🚀 Quick Start

$3

Cross-Platform Binaries (Recommended):
``bash

`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:`bash git clone https://github.com/vsmash/nodemaiass.git cd nodemaiass && npm install && npm link`

`$3`

`bash

`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

$3

`bash

`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
$3
$3
$3
🌍 Platform Support

`🔄 Workflow Overview`

MAIASS orchestrates a 4-phase intelligent workflow:

`⚙️ Quick Configuration`

`bash

`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?
$3
$3
$3
🔗 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.

`bash

`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 
maiass config set  
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
$3

1. Enable AI features (optional):`bash # Set Maiass API key globally maiass config --global maiass_token=your_api_key_here`

2. Project-specific settings (if needed):`bash # Override branch names for projects using 'main' maiass config --project mainbranch=main`

`$3`

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

`$3`

`bash

`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:
$3
$3
$3
$3

  -

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:
$3

User-facing format with clean, readable entries:

markdown
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


$3

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

markdown
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)


$3
🎨 Examples
$3

bash
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

$3

bash
Just commit changes without version bumping

maiass --commits-only --auto-stage
With AI commit message

maiass commit

$3

bash
Preview what would happen without making changes

maiass --dry-run patch
Check current version status

maiass version --current


🔧 Advanced Usage
$3

bash
Configure custom version file

maiass config --project version_primary_file=VERSION.txt
maiass config --project version_primary_type=text

$3

bash
Update multiple files with same version

maiass config --project version_secondary_files="src/version.js,docs/VERSION"

$3

bash
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
$3

"Not in a git repository"`bash

`Ensure you're in a git repository`


git status

"No version files detected"`bash

`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"`bash

`Create develop branch if it doesn't exist`


git checkout -b develop

$3

bash
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