markitect-main/INSTALL.md

# MarkiTect Installation Guide

This document describes how to install MarkiTect and make it available system-wide.

## Quick Installation

For most users, the quick installer is the easiest option:

```bash
# Install for current user
./install.sh

# Install system-wide (requires sudo)
./install.sh --system

# Install in development mode with test dependencies
./install.sh --dev
```

## Advanced Installation

For more control over the installation process, use the Python installer:

```bash
# Install with custom prefix
python install.py --prefix /opt/markitect

# Install with custom virtual environment location
python install.py --venv-dir /path/to/custom/venv

# Install without creating symbolic links (manual PATH setup)
python install.py --no-symlinks

# Force reinstallation over existing installation
python install.py --force
```

## Installation Options

### Installation Types

- **User Installation** (default): Installs to `~/.local/`
- **System Installation** (`--system`): Installs to `/usr/local/` (requires sudo)
- **Development Installation** (`--dev`): Installs in editable mode with test dependencies

### Installation Paths

By default, MarkiTect is installed to:

- **User installation**: `~/.local/lib/markitect/` (virtual environment)
- **System installation**: `/usr/local/lib/markitect/` (virtual environment)
- **Binaries**: `~/.local/bin/` or `/usr/local/bin/`

### Available Commands

After installation, these commands will be available:

- `markitect` - Main MarkiTect CLI
- `tddai` - TDD workflow management
- `issue` - Issue management

## Checking Installation

Check if MarkiTect is already installed:

```bash
./install.sh --check
# or
python install.py --check
```

Check version after installation:

```bash
markitect version
markitect version --short
markitect release
```

## Uninstallation

To remove MarkiTect:

```bash
./install.sh --uninstall
# or
python install.py --uninstall
```

## Manual Installation

If you prefer to install manually:

1. **Create virtual environment:**
   ```bash
   python -m venv ~/.local/lib/markitect
   ```

2. **Activate virtual environment:**
   ```bash
   source ~/.local/lib/markitect/bin/activate
   ```

3. **Install MarkiTect:**
   ```bash
   pip install -e .
   ```

4. **Create symbolic links:**
   ```bash
   mkdir -p ~/.local/bin
   ln -sf ~/.local/lib/markitect/bin/markitect ~/.local/bin/markitect
   ln -sf ~/.local/lib/markitect/bin/tddai ~/.local/bin/tddai
   ln -sf ~/.local/lib/markitect/bin/issue ~/.local/bin/issue
   ```

5. **Add to PATH** (add to `~/.bashrc` or `~/.zshrc`):
   ```bash
   export PATH="$HOME/.local/bin:$PATH"
   ```

## Development Installation

For development work:

```bash
# Install in development mode
./install.sh --dev

# This includes:
# - Editable installation (changes reflect immediately)
# - Test dependencies (pytest, black, flake8, mypy)
# - All development tools
```

## Troubleshooting

### Common Issues

1. **Command not found after installation:**
   - Make sure `~/.local/bin` is in your PATH
   - Run: `export PATH="$HOME/.local/bin:$PATH"`
   - Add the export to your shell profile

2. **Permission denied on system installation:**
   - Use `sudo ./install.sh --system`
   - Or install to user directory instead

3. **Python version error:**
   - MarkiTect requires Python 3.8 or higher
   - Check version: `python3 --version`

4. **Installation already exists:**
   - Use `--force` to overwrite: `./install.sh --force`
   - Or uninstall first: `./install.sh --uninstall`

### Manual PATH Setup

If symbolic links don't work, add the virtual environment bin directory to your PATH:

```bash
# For bash/zsh (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/lib/markitect/bin:$PATH"

# For fish (add to ~/.config/fish/config.fish)
set -gx PATH $HOME/.local/lib/markitect/bin $PATH
```

### Testing Installation

After installation, verify everything works:

```bash
# Test basic functionality
markitect --help
markitect version

# Test TDD tools
tddai --help

# Test issue management
issue --help
```

## Dependencies

MarkiTect automatically installs these dependencies:

### Production Dependencies
- markdown-it-py - Markdown parsing
- PyYAML - YAML processing
- click>=8.0.0 - CLI framework
- tabulate>=0.9.0 - Table formatting
- jsonpath-ng>=1.5.0 - JSONPath queries
- aiohttp>=3.8.0 - Async HTTP client
- toml - TOML file parsing

### Development Dependencies (with --dev)
- pytest - Testing framework
- pytest-cov - Test coverage
- black - Code formatting
- flake8 - Code linting
- mypy - Type checking

## System Requirements

- Python 3.8 or higher
- pip (Python package installer)
- git (optional, for version info)
- Unix-like system (Linux, macOS) or Windows with Python support

## Support

For installation issues:

1. Check this guide first
2. Run `./install.sh --check` to diagnose problems
3. See the main project documentation
4. Report issues on the project issue tracker