npm package: @kishar/haya
Description: Git wrapper for managing multiple identities
Author: Syam Farijal
Latest version: 1.0.2

# Haya 🔱

**Git Identity Manager with Intelligence** — Named after the Mesopotamian god of records, Haya is your wise mentor for managing Git identities and navigating the complexities of version control. Perfect for solo developers who forget to pull and teams who need conflict guidance.

## ✨ What's New in 2.0

- **🧙 Mentor Voice** — Haya guides you through conflicts like a patient teacher, not a robotic tool
- **🔮 Smart Conflict Resolution** — Automatic stash, merge, and conflict handling with safety backups
- **👥 Team Detection** — Automatically detects collaboration and adapts behavior
- **📝 Conventional Commits** — Built-in support for standardized commit messages (feat:, fix:, etc.)
- **⚡ Deity Mode** — Unlock mythological personality with `--deity-mode` flag
- **💾 Auto-Backup** — Never lose work with automatic backup branches before risky operations

## Features

- **🎭 Multi-Profile Support** — Create and manage unlimited identity profiles
- **📦 Smart Clone** — Clone repositories with automatic SSH host alias rewriting. Supports standard URLs (`git@`, `https://`) and short syntax (`user/repo`)
- **🚀 Quick Init** — Initialize new repos with pre-configured identity
- **⚙️ Local Config** — Automatically sets `user.name` and `user.email` per repository
- **🔄 Smart Sync** — Intelligent pull → commit → push workflow with conflict prevention
- **📊 Status Insights** — See ahead/behind commits, team activity, and sync state
- **📡 Connection Testing** — Verify SSH connections for your profiles
- **🎯 Interactive Menu** — Run `haya` without arguments for a guided experience

## Installation

### From npm

```bash
npm install -g @kishar/haya
```

### From Source

```bash
git clone https://github.com/syam-fh/haya.git
cd haya
npm install
npm link
```

## Quick Start

### 1. Configure Your First Profile

```bash
haya config
```

You'll be prompted to enter:
- **Profile name** (e.g., "Work", "Personal")
- **Git username**
- **Git email**
- **SSH Host alias** (e.g., `github.com-work`)

### 2. Set Up SSH Config

Make sure your `~/.ssh/config` matches your profile's SSH host alias:

```ssh
# Work GitHub
Host github.com-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work

# Personal GitHub
Host github.com-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
```

### 3. Clone with Identity

You can use the full URL or the short `user/repo` syntax:

```bash
# Short syntax (GitHub) - Automatically uses your profile's SSH host
haya clone my-org/backend-api

# Standard URL
haya clone git@github.com:my-org/backend-api.git
```

Select your profile, and Haya will:
1. Rewrite the URL to use your SSH host alias (e.g., `git@github.com-work:my-org/backend-api.git`)
2. Clone the repository
3. Configure local `user.name` and `user.email`

## Commands

| Command | Description |
|---------|-------------|
| `haya` | Show interactive menu |
| `haya clone <url\|user/repo>` | Clone repository with identity profile. Supports `user/repo` shortcut |
| `haya init [directory]` | Initialize new repository with identity profile |
| `haya commit` | Stage all changes and commit |
| `haya pull` | Pull changes from remote origin |
| `haya push` | Push changes to remote origin (checks for remote updates first) |
| `haya sync` | **Recommended**: All-in-one workflow (pull → commit → push) |
| `haya status` | Show repository sync status (ahead/behind remote, uncommitted changes) |
| `haya ping [profile]` | Test SSH connection for a specific profile |
| `haya config` | Manage identity profiles |
| `haya --help` | Show help message |

## Working Across Multiple Devices

Haya is designed to make multi-device development seamless. Here's how to avoid conflicts:

### Best Practices

**Option 1: Use `haya sync` (Recommended)**
```bash
# At the end of your work session
haya sync
```
This automatically pulls latest changes, commits your work, and pushes everything in one command.

**Option 2: Manual workflow**
```bash
# At start of work session
haya pull

# ... do your work ...

# At end of work session
haya commit
haya push
```

### Checking Repository Status

Before you start working, check your sync status:
```bash
haya status
```

This shows:
- Current branch
- Uncommitted changes
- How many commits you're ahead/behind remote
- SSH profile alignment

### Handling Conflicts

If you forgot to pull and made changes on another device, `haya push` will warn you:

```bash
$ haya push
⚠️  Warning: Remote has 3 new commits that you don't have locally!
? Do you want to pull first? (Recommended) (Y/n)
```

If conflicts occur during pull:
1. Run `git status` to see conflicted files
2. Edit files and resolve conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
3. Run `git add .`
4. Run `git commit`
5. Run `haya push`

## Haya's Personality - Meet Your Mentor

Haya isn't just a tool—it's a guide. Named after the Mesopotamian god of records, Haya speaks with wisdom and patience.

### Mentor Mode (Default)

Professional, warm guidance for developers:

```
🔱 Haya: Hold on. I notice the server has code you don't have yet.

If you push now, we might create conflicts that are messy to fix.
Better to get that code first, then push yours on top.

What would you like to do?
1. Pull first, then push (I recommend this)
2. Force push anyway (risky - might lose server code)
3. Cancel and let me handle it manually
```

### Deity Mode 

Unlock the full mythological personality:

```bash
haya push --deity-mode
```

```
⚡ Haya speaks: I sense disturbances in the cosmic record...

The celestial archive holds 3 inscriptions unknown to your mortal realm.
Pushing now would fracture the timeline and scatter the sacred texts.

Choose wisely, mortal:
1. Retrieve the celestial wisdom first (the divine path)
2. My truth shall overwrite the heavens (hubris!)
3. I shall consult the stars myself
```

### Minimal Mode

For CI/CD and automated workflows - facts only, no personality:

```bash
haya config --set voice=minimal
```

## Smart Conflict Resolution

Haya v2.0 handles conflicts intelligently, so you don't have to be a Git expert.

### Automatic Strategies

When conflicts arise, Haya:

1. **Creates safety backups** - Automatic `haya-backup-TIMESTAMP` branches
2. **Attempts smart resolution** - Keeps your working code, accepts config changes
3. **Guides you step-by-step** - Clear options without Git jargon
4. **Never loses work** - Stashes, backups, and graceful failures

### Example: Forgot to Pull

```bash
$ haya push

🔱 Haya: Hold on. I notice the server has 2 commits you don't have yet.

If you push now, we might create conflicts...
What would you like to do?
1. Pull first, then push (I recommend this)
```

Select option 1:

```
📥 Pulling changes first...
💾 Saving your uncommitted work temporarily...
📦 Restoring your work...

✅ Pulled 2 file(s) successfully
💡 Now run "haya push" again to push your changes.
```

No conflicts! All changes merged safely.

### Guided Resolution

When conflicts can't be auto-resolved:

```
🔱 Haya: We have a problem to solve together.

The same file was changed in two places:
  • src/api.ts

This is called a conflict. It happens in teams.

I can help you resolve this:
1. Keep my changes (use my version)
2. Keep server changes (use server version)
3. I'll resolve manually with git
```

## Conventional Commits Support

Haya v2.0 supports [Conventional Commits](https://www.conventionalcommits.org/) format out of the box with smart defaults.

### What are Conventional Commits?

Standardized commit message format used by modern teams:

```
<type>(<scope>): <description>

[optional body]
```

**Common types:**
- `feat:` - New feature
- `fix:` - Bug fix  
- `chore:` - Maintenance
- `docs:` - Documentation
- `refactor:` - Code restructuring

### Smart Type Detection

Haya analyzes your changed files and suggests the right type:

```bash
$ haya commit

📋 Changes to be committed:
   📝 README.md

📝 Let's build a conventional commit...

✔ Commit type: › docs     - Documentation only  ← Auto-suggested!
✔ Scope (optional): ›
✔ Short description: › add conflict resolution guide

Preview:
   docs: add conflict resolution guide

✅ Commit successful!
```

### Quick Mode in Sync

`haya sync` uses quick conventional commits with minimal prompts:

```bash
$ haya sync

Step 2/3: Recording your changes...
   Found 3 changes

✔ Commit message (feat): › add voice system

# Becomes: feat: add voice system
```

### Enable Conventional Commits

```bash
# Make it your default
haya config --set commitStyle=conventional

# Or Haya will prompt you to try it
$ haya commit
✔ Use conventional commit format? › Yes

# It will even ask if you want to make it default!
```

### Team Mode Auto-Enables

When team mode is detected, Haya automatically uses conventional commits for consistency.

## Configuration

### Voice & Behavior Settings

Customize Haya's personality and behavior:

```bash
# Set voice mode
haya config --set voice=deity        # Mythological personality
haya config --set voice=mentor       # Professional guide (default)
haya config --set voice=minimal      # Facts only

# Enable team-safe mode
haya config --set teamMode=true      # Extra caution for collaboration

# Set commit style
haya config --set commitStyle=conventional  # Use conventional commits
haya config --set commitStyle=freeform      # Traditional commit messages

# View current settings
haya config --show
```

### Identity Profiles

Profiles are stored in `~/.config/haya/haya.conf`:

```json
{
  "profiles": {
    "work": {
      "name": "Work",
      "username": "john-work",
      "email": "john@company.com",
      "sshHost": "github.com-work"
    },
    "personal": {
      "name": "Personal",
      "username": "johndoe",
      "email": "john@personal.com",
      "sshHost": "github.com-personal"
    }
  }
}
```

## Requirements

- Node.js >= 16.0.0
- Git installed and available in PATH

## License

MIT © [Syam](https://github.com/syam-fh)