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:

# 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:

# 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:

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

Check version after installation:

markitect version
markitect version --short
markitect release

Uninstallation

To remove MarkiTect:

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

Manual Installation

If you prefer to install manually:

1. Create virtual environment:

   python -m venv ~/.local/lib/markitect
   

2. Activate virtual environment:

   source ~/.local/lib/markitect/bin/activate
   

3. Install MarkiTect:

   pip install -e .
   

4. Create symbolic links:

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

   export PATH="$HOME/.local/bin:$PATH"
   

Development Installation

For development work:

# 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:

# 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:

# 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