# Persuade (Generic AI Development Tool Configurator)

A powerful CLI tool to sync Claude Code automation from this template repository to your target projects.

## Features

- **Smart Syncing**: Intelligent file categorization (sync, merge, skip, copy-once)
- **Settings Merging**: Preserves your local settings while importing template updates
- **Backup & Rollback**: Automatic backups before each sync with easy rollback
- **Shadow Mode**: Sync files but exclude from git (perfect for open-source projects)
- **Editable Mode**: Symlink files for live development on the template
- **Validation**: Doctor command to check and fix common misconfigurations

## Installation

### From Source (Development)

```bash
# Clone this repository
git clone https://github.com/stavxyz/persuade.git
cd persuade

# Install in editable mode
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

# Verify installation
persuade --version
```

### From Git (Direct Install)

```bash
pip install git+https://github.com/stavxyz/persuade.git
```

### Production Install (PyPI - Coming Soon)

```bash
pip install persuade
```

## Quick Start

### Basic Sync

```bash
# Sync Claude Code automation to your project
persuade sync ~/projects/my-app

# Preview changes without applying (dry run)
persuade sync --dry-run ~/projects/my-app
```

### Shadow Mode (Open Source Projects)

```bash
# Sync files but exclude from git (adds to .gitignore)
persuade sync --shadow ~/projects/open-source-app
```

### Editable Mode (Template Development)

```bash
# Symlink files for live development
persuade sync --editable ~/projects/my-app

# Changes to template instantly reflect in target
```

## Commands

### `persuade sync`

Sync Claude Code automation to target project.

**Options:**
- `--dry-run`: Preview changes without applying
- `--strict`: Remove non-template permissions
- `--force`: Skip confirmation prompts
- `--no-backup`: Skip backup creation (not recommended)
- `--exclude PATTERN`: Exclude files matching pattern (can be used multiple times)
- `--shadow`: Sync files but exclude from git
- `--editable, -e`: Symlink files for live development

**Examples:**
```bash
# Basic sync with backup
persuade sync ~/projects/my-app

# Preview changes
persuade sync --dry-run ~/projects/my-app

# Exclude specific patterns
persuade sync --exclude "*.yml" --exclude "hooks/*" ~/projects/my-app

# Shadow mode for open-source projects
persuade sync --shadow ~/projects/open-source-app
```

### `persuade doctor`

Validate and fix common misconfigurations.

**Options:**
- `--fix`: Automatically fix issues
- `--check-only`: Only report issues, don't fix

**Examples:**
```bash
# Check for issues
persuade doctor ~/projects/my-app

# Check and fix issues
persuade doctor --fix ~/projects/my-app
```

### `persuade help-command`

Show installation state and help for a project.

**Example:**
```bash
persuade help-command ~/projects/my-app
```

### `persuade rollback`

Restore from backup.

**Options:**
- `--list`: List available backups
- `--timestamp TIMESTAMP`: Restore specific backup
- `--latest`: Restore most recent backup

**Examples:**
```bash
# List backups
persuade rollback --list ~/projects/my-app

# Restore latest backup
persuade rollback --latest ~/projects/my-app

# Restore specific backup
persuade rollback --timestamp 20231215_143022 ~/projects/my-app
```

### `persuade validate-docs`

Validate Python code examples in documentation.

**Options:**
- `--strict`: Enable strict type checking with mypy

**Examples:**
```bash
# Validate with syntax checking only (default)
persuade validate-docs

# Validate custom documentation path
persuade validate-docs docs/

# Enable strict mypy type checking
persuade validate-docs --strict

# Combine custom path with strict checking
persuade validate-docs docs/ --strict
```

**Alternative invocation:**
```bash
# Run directly as a module
python -m persuade.docs.validate
python -m persuade.docs.validate --strict
```

## File Categories

Persuade categorizes files into four types:

1. **SYNC_ALWAYS**: Commands, hooks, scripts - always overwritten
2. **MERGE_SMART**: `settings.json` - intelligently merged
3. **SKIP_ALWAYS**: `settings.local.json`, state/, logs/ - never synced
4. **COPY_IF_MISSING**: README - copied only if missing

## Directory Structure

After syncing, your project will have:

```
your-project/
├── .claude/
│   ├── commands/       # Custom Claude commands
│   ├── hooks/          # Claude event hooks
│   ├── git-hooks/      # Git hooks (installed to .git/hooks/)
│   ├── scripts/        # Automation scripts
│   ├── prompts/        # Reusable prompts
│   ├── docs/           # AI-optimized engineering standards
│   ├── knowledge/      # Knowledge base
│   ├── settings.json   # Claude settings (merged)
│   ├── state/          # Runtime state (local only)
│   ├── logs/           # Debug logs (local only)
│   └── .backup/        # Sync backups (local only)
├── .git/
│   └── hooks/          # Git hooks (synced from .claude/git-hooks/)
└── .github/
    └── workflows/      # CI/CD workflows (if present in template)
```

## Advanced Usage

### Custom Exclude Patterns

```bash
# Exclude multiple patterns
persuade sync \
  --exclude "workflows/*.yml" \
  --exclude "hooks/pre-push" \
  ~/projects/my-app
```

### Verbose Output

```bash
# See detailed sync information
persuade -v sync ~/projects/my-app
```

### Quiet Mode

```bash
# Minimal output (useful for scripts)
persuade -q sync ~/projects/my-app
```

## Troubleshooting

### "Permission denied" errors

Ensure scripts are executable after sync:
```bash
chmod +x .claude/scripts/*.sh
chmod +x .claude/hooks/*.sh
```

### Merge conflicts in settings.json

Persuade intelligently merges settings, but you can:
1. Check backup: `persuade rollback --list ~/projects/my-app`
2. Restore if needed: `persuade rollback --latest ~/projects/my-app`
3. Manually edit `.claude/settings.json`

### Symlinks not working (Windows)

Windows requires Developer Mode or Administrator privileges for symlinks:
1. Enable Developer Mode in Windows Settings
2. Or run terminal as Administrator

### Files not syncing

Check if files are:
1. Gitignored: `git check-ignore <file>`
2. Excluded by pattern: `persuade sync --dry-run -v ~/projects/my-app`
3. In skip patterns: Check `persuade/constants.py::SKIP_PATTERNS`

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/unit/persuade/ -v

# With coverage
pytest tests/unit/persuade/ --cov=persuade --cov-report=term-missing
```

### Code Quality

```bash
# Lint and format
ruff check --fix persuade/
ruff format persuade/

# Type check
mypy persuade/
```

## Dependencies

- Python ≥ 3.11
- click ≥ 8.1.0 (CLI framework)
- rich ≥ 13.0.0 (terminal formatting)

## License

MIT License - See repository LICENSE file

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

## Support

- **Issues**: [GitHub Issues](https://github.com/stavxyz/persuade/issues)
- **Discussions**: [GitHub Discussions](https://github.com/stavxyz/persuade/discussions)
