hmm-git-safety/PROJECT_STRUCTURE.md

A safety wrapper for git push that prevents accidental pushes to origin without branch name

# hmm Project Structure

Complete overview of the hmm git safety wrapper project.

## Directory Tree

```
hmm/
├── bin/                      # Executable binaries and scripts
│   ├── hmm                  # Python CLI executable
│   ├── hmm-cli.js           # Node.js CLI executable
│   ├── install.js           # NPM post-install script
│   └── uninstall.js         # NPM pre-uninstall script
│
├── hmm.sh                   # Core shell function wrapper
├── install.sh               # Unix shell installation script
├── uninstall.sh             # Unix shell uninstallation script
├── gui_installer.py         # Cross-platform GUI installer (tkinter)
├── demo.sh                  # Demo script showing functionality
│
├── package.json             # NPM package configuration
├── index.js                 # NPM package entry point
├── setup.py                 # Python package configuration
├── MANIFEST.in              # Python package manifest
├── hmm.rb                   # Homebrew formula
│
├── README.md                # Main documentation
├── QUICKSTART.md            # Quick start guide
├── CONTRIBUTING.md          # Contribution guidelines
├── PROJECT_STRUCTURE.md     # This file
├── LICENSE                  # MIT License
└── .gitignore              # Git ignore patterns
```

## Installation Methods

### 1. NPM Package (`npm install -g hmm-git-safety`)
- Entry point: `index.js`
- CLI: `bin/hmm-cli.js`
- Auto-installer: `bin/install.js` (runs post-install)
- Auto-uninstaller: `bin/uninstall.js` (runs pre-uninstall)

### 2. Python Package (`pip install hmm-git-safety`)
- Setup: `setup.py`
- CLI: `bin/hmm`
- Auto-installer: Runs via `PostInstallCommand` in setup.py

### 3. Homebrew (`brew install hmm`)
- Formula: `hmm.rb`
- Runs `install.sh` via post_install hook

### 4. Direct Shell Script
- Installer: `install.sh`
- Uninstaller: `uninstall.sh`
- Core: `hmm.sh`

### 5. GUI Installer
- Application: `gui_installer.py`
- Cross-platform (Windows, macOS, Linux)
- Uses Python tkinter

## Core Components

### hmm.sh - The Heart of the Project
This is the actual git wrapper function that provides safety checks:
```bash
git() {
  if [[ "$1" == "push" && "$2" == "origin" && -z "$3" ]]; then
    # 3 confirmation prompts with colored warnings
  fi
  command git "$@"
}
```

### Shell Installation Logic
All installers ultimately add the git function to the user's shell config:
- Detects shell (zsh, bash, or fallback)
- Locates config file (~/.zshrc, ~/.bashrc, ~/.profile)
- Appends the function between marker comments
- Prevents duplicate installations

### CLI Tools
Provide management commands:
- `hmm install` - Install the wrapper
- `hmm uninstall` - Remove the wrapper
- `hmm status` - Check installation status
- `hmm help` - Show usage information

## File Purposes

| File | Purpose |
|------|---------|
| `hmm.sh` | Core shell function (standalone use) |
| `install.sh` | Direct shell installation |
| `uninstall.sh` | Direct shell uninstallation |
| `bin/hmm` | Python CLI tool |
| `bin/hmm-cli.js` | Node.js CLI tool |
| `bin/install.js` | NPM installation logic |
| `bin/uninstall.js` | NPM uninstallation logic |
| `setup.py` | Python package setup and auto-install |
| `package.json` | NPM package metadata and scripts |
| `index.js` | NPM package entry point (exports modules) |
| `hmm.rb` | Homebrew formula for macOS |
| `gui_installer.py` | GUI installer application |
| `demo.sh` | Demonstration script |
| `MANIFEST.in` | Python package file inclusions |

## Supported Platforms

### Operating Systems
- macOS (primary target)
- Linux (all major distributions)
- Windows (via WSL or Git Bash)

### Shells
- zsh (default on modern macOS)
- bash (most Linux systems)
- Others via ~/.profile fallback

### Package Managers
- npm/npx (Node.js ecosystem)
- pip (Python ecosystem)
- Homebrew (macOS)
- Direct download (universal)

## How It Works

1. **Installation**: Wrapper function is added to shell config file
2. **Shell Loading**: Function is loaded when terminal starts
3. **Git Command**: User types `git push origin`
4. **Interception**: Shell function intercepts before real git runs
5. **Safety Check**: Detects missing branch parameter
6. **Confirmations**: Asks user 3 times for explicit confirmation
7. **Execution**: Either proceeds with real git or cancels

## Customization Points

Users or contributors can customize:
- Number of confirmations (currently 3)
- Warning messages
- Color scheme
- Additional git commands to protect
- Shell config file detection logic

## Testing Checklist

Before release, test:
- [ ] Installation via npm
- [ ] Installation via pip
- [ ] Installation via shell script
- [ ] Installation via GUI
- [ ] Functionality on zsh
- [ ] Functionality on bash
- [ ] Uninstallation via all methods
- [ ] Status checking
- [ ] Multiple install attempts (should detect existing)
- [ ] Cross-platform compatibility

## Future Enhancements

Potential additions:
- Fish shell support
- PowerShell support
- Configurable confirmation count
- Custom warning messages via config file
- Repository whitelist
- Integration with git hooks
- Support for other dangerous git commands
- Telemetry/analytics (opt-in)

## Package Publishing

### NPM
```bash
npm login
npm publish
```

### PyPI
```bash
python -m build
python -m twine upload dist/*
```

### Homebrew
- Create GitHub release
- Submit to homebrew-core
- Or maintain personal tap

## Security Considerations

- No network calls
- No data collection
- Modifies user's shell config (clearly documented)
- Easy to uninstall
- Open source and auditable
- No elevated permissions required

## License

MIT License - See LICENSE file for details