From 149c03d7a3a7be68f953d7ef554ec6ba1ddb7e72 Mon Sep 17 00:00:00 2001 From: gnarzilla Date: Tue, 12 Nov 2024 22:21:12 -0700 Subject: [PATCH] Added documentation including changelog, contributing and readme --- CHANGELOG.md | 14 ++++ CONTRIBUTING.md | 54 ++++++++++++++ README.md | 195 ++++++++++++++++++++---------------------------- README_og.md | 155 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 302 insertions(+), 116 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 README_og.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f4a8050 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2024-11-12 + +### Added +- Initial release with core functionality +- Authentication management (SSH, GitHub) +- Configuration management +- Hook management diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..07e25c1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing to deadlight-guardian + +We love your input! We want to make contributing as easy and transparent as possible. + +## Development Process + +1. Fork the repo and create your branch from `main`. +2. If you've added code that should be tested, add tests. +3. Update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. +6. Issue a pull request. + +## Any contributions you make will be under the MIT License +When you submit code changes, your submissions are understood to be under the same [MIT License](LICENSE) that covers the project. + +## Report bugs using GitHub's [issue tracker] +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](). + +## Write bug reports with detail, background, and sample code + +**Great Bug Reports** tend to have: + +- A quick summary and/or background +- Steps to reproduce + - Be specific! + - Give sample code if you can. +- What you expected would happen +- What actually happens +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) + +## Development Setup + +1. Clone the repository +2. Create a virtual environment: `python -m venv venv` +3. Activate the environment: `source venv/bin/activate` +4. Install dependencies: `pip install -e ".[dev]"` +5. Install pre-commit hooks: `guardian hooks install` + +## Testing + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=guardian +``` + +## Pull Request Process + +1. Update the README.md with details of changes if needed. +2. Update the CHANGELOG.md with notes on your changes. +3. The PR will be merged once you have the sign-off of another developer. diff --git a/README.md b/README.md index 4d570d7..a508537 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,117 @@ -# Guardian +# deadlight-guardian -``` - ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗ ██╗ █████╗ ███╗ ██╗ - ██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗██║██╔══██╗████╗ ██║ - ██║ ███╗██║ ██║███████║██████╔╝██║ ██║██║███████║██╔██╗ ██║ - ██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║██║██╔══██║██║╚██╗██║ - ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝██║██║ ██║██║ ╚████║ - ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝ -``` - -[![PyPI version](https://badge.fury.io/py/guardian-git.svg)](https://badge.fury.io/py/guardian-git) -[![CI Status](https://github.com/yourusername/guardian/workflows/CI/badge.svg)](https://github.com/yourusername/guardian/actions) -[![Documentation Status](https://readthedocs.org/projects/guardian-git/badge/?version=latest)](https://guardian-git.readthedocs.io/en/latest/?badge=latest) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) - -Git User Authentication & Repository Development Interface Assistant & Navigator +Git Authentication & Development Interface Assistant & Navigator ## Features -🔒 **Secure Authentication Management** -- SSH key generation and management -- Personal Access Token secure storage -- GitHub CLI credential management -- System keyring integration - -🧩 **Configuration Management** -- Git config backup and restore -- SSH key backup with encryption -- Automated config migration - -🧪 **Code Quality Tools** -- Pre-commit hook automation -- Code formatting with black -- Import sorting with isort -- Type checking with mypy - -📊 **Security Features** -- Audit logging for auth events -- Key rotation management -- Configurable security levels -- Encrypted backup storage +### Cli +Guardian: Git Authentication & Development Assistant + + A comprehensive tool for managing Git authentication, security, + and development workflows. + + +### Auth +Authentication management commands + +- `cli auth setup-github`: Configure GitHub Personal Access Token (PAT) for authentication +- `cli auth setup-ssh`: Generate and configure SSH keys +- `cli auth status`: Check status of all authentication methods +- `cli auth validate-github`: Validate GitHub token and show its capabilities +- `cli auth list`: List configured authentication methods +- `cli auth debug-tokens`: Debug token storage (development only) +- `cli auth debug-service`: Debug auth service configuration +- `cli auth setup-signing`: Setup GPG key for commit signing +### Config +Configuration management commands + +- `cli config set`: Set a configuration value +- `cli config get`: Get a configuration value +- `cli config unset`: Remove a configuration value +- `cli config init`: Initialize configuration with defaults +### Hooks +Pre-commit hook management + +- `cli hooks templates`: List available hook templates +- `cli hooks install`: Install Git hooks using specified template +- `cli hooks list`: List installed hooks and their status +- `cli hooks show`: Show content of an installed hook +- `cli hooks remove`: Remove an installed hook +### Format +Code formatting commands + +- `cli format run`: Format code using configured formatters +- `cli format configure`: Configure formatting settings +- `cli init`: Initialize Guardian in the current directory +### Repo +Repository and remote management commands + +- `cli repo create`: Create a remote repository for the current project +- `cli repo connect`: Connect existing repository to a remote +- `cli repo sync`: Synchronize repository configuration across systems +- `cli repo apply-sync`: Apply synchronized configuration from .guardian-sync.yml ## Installation -### Via pip (recommended) -```bash -pip install guardian-git -``` - -### From source ```bash -git clone https://github.com/yourusername/guardian.git -cd guardian -pip install -e ".[dev]" +pip install deadlight-guardian ``` ## Quick Start -### Authentication Setup ```bash # Initialize Guardian guardian init -# Setup SSH authentication +# Setup authentication guardian auth setup-ssh - -# Configure GitHub tokens guardian auth setup-github -``` -### Code Quality Tools -```bash -# Install pre-commit hooks -guardian hooks install +# Check status +guardian auth status +``` -# Format code -guardian format . +## Usage Examples -# Run all checks -guardian check -``` +Here are some common use cases: -### Configuration Management +### Setting up a new machine ```bash -# Backup current configuration -guardian backup create +# Install Guardian +pip install deadlight-guardian -# Restore from backup -guardian backup restore +# Setup authentication +guardian auth setup-ssh +guardian auth setup-github -# Rotate SSH keys -guardian auth rotate-keys +# Verify setup +guardian auth status ``` -## CLI Reference - -### Main Commands -- `guardian init`: Initialize Guardian in current directory -- `guardian auth`: Authentication management commands -- `guardian format`: Code formatting commands -- `guardian hooks`: Pre-commit hook management -- `guardian backup`: Configuration backup commands -- `guardian check`: Run all configured checks +### Managing Git configurations +```bash +# View current configuration +guardian config get -### Command Groups -``` -guardian/ -├── auth/ -│ ├── setup-ssh # SSH key setup -│ ├── setup-github # GitHub token setup -│ └── rotate-keys # Key rotation -├── format/ -│ ├── run # Run formatters -│ └── check # Check formatting -└── hooks/ - ├── install # Install pre-commit hooks - └── update # Update hook configurations +# Set configuration +guardian config set user.name "Your Name" +guardian config set user.email "your@email.com" ``` -## Configuration - -Guardian can be configured via `guardian.yaml` in your project root: - -```yaml -security: - level: enhanced # basic, enhanced, or paranoid - backup_encryption: true - audit_logging: true - -formatting: - black_enabled: true - isort_enabled: true - mypy_enabled: true +### Working with hooks +```bash +# Install hooks +guardian hooks install -hooks: - pre_commit: - - black - - isort - - mypy +# View installed hooks +guardian hooks list ``` -## Contributing +For more examples and detailed documentation, visit our [documentation site](docs/). -Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. +## Contributing -### Development Setup -1. Clone the repository -2. Install development dependencies: `pip install -e ".[dev]"` -3. Install pre-commit hooks: `pre-commit install` -4. Run tests: `pytest` +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ## License diff --git a/README_og.md b/README_og.md new file mode 100644 index 0000000..4d570d7 --- /dev/null +++ b/README_og.md @@ -0,0 +1,155 @@ +# Guardian + +``` + ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗ ██╗ █████╗ ███╗ ██╗ + ██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗██║██╔══██╗████╗ ██║ + ██║ ███╗██║ ██║███████║██████╔╝██║ ██║██║███████║██╔██╗ ██║ + ██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║██║██╔══██║██║╚██╗██║ + ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝██║██║ ██║██║ ╚████║ + ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝ +``` + +[![PyPI version](https://badge.fury.io/py/guardian-git.svg)](https://badge.fury.io/py/guardian-git) +[![CI Status](https://github.com/yourusername/guardian/workflows/CI/badge.svg)](https://github.com/yourusername/guardian/actions) +[![Documentation Status](https://readthedocs.org/projects/guardian-git/badge/?version=latest)](https://guardian-git.readthedocs.io/en/latest/?badge=latest) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +Git User Authentication & Repository Development Interface Assistant & Navigator + +## Features + +🔒 **Secure Authentication Management** +- SSH key generation and management +- Personal Access Token secure storage +- GitHub CLI credential management +- System keyring integration + +🧩 **Configuration Management** +- Git config backup and restore +- SSH key backup with encryption +- Automated config migration + +🧪 **Code Quality Tools** +- Pre-commit hook automation +- Code formatting with black +- Import sorting with isort +- Type checking with mypy + +📊 **Security Features** +- Audit logging for auth events +- Key rotation management +- Configurable security levels +- Encrypted backup storage + +## Installation + +### Via pip (recommended) +```bash +pip install guardian-git +``` + +### From source +```bash +git clone https://github.com/yourusername/guardian.git +cd guardian +pip install -e ".[dev]" +``` + +## Quick Start + +### Authentication Setup +```bash +# Initialize Guardian +guardian init + +# Setup SSH authentication +guardian auth setup-ssh + +# Configure GitHub tokens +guardian auth setup-github +``` + +### Code Quality Tools +```bash +# Install pre-commit hooks +guardian hooks install + +# Format code +guardian format . + +# Run all checks +guardian check +``` + +### Configuration Management +```bash +# Backup current configuration +guardian backup create + +# Restore from backup +guardian backup restore + +# Rotate SSH keys +guardian auth rotate-keys +``` + +## CLI Reference + +### Main Commands +- `guardian init`: Initialize Guardian in current directory +- `guardian auth`: Authentication management commands +- `guardian format`: Code formatting commands +- `guardian hooks`: Pre-commit hook management +- `guardian backup`: Configuration backup commands +- `guardian check`: Run all configured checks + +### Command Groups +``` +guardian/ +├── auth/ +│ ├── setup-ssh # SSH key setup +│ ├── setup-github # GitHub token setup +│ └── rotate-keys # Key rotation +├── format/ +│ ├── run # Run formatters +│ └── check # Check formatting +└── hooks/ + ├── install # Install pre-commit hooks + └── update # Update hook configurations +``` + +## Configuration + +Guardian can be configured via `guardian.yaml` in your project root: + +```yaml +security: + level: enhanced # basic, enhanced, or paranoid + backup_encryption: true + audit_logging: true + +formatting: + black_enabled: true + isort_enabled: true + mypy_enabled: true + +hooks: + pre_commit: + - black + - isort + - mypy +``` + +## Contributing + +Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. + +### Development Setup +1. Clone the repository +2. Install development dependencies: `pip install -e ".[dev]"` +3. Install pre-commit hooks: `pre-commit install` +4. Run tests: `pytest` + +## License + +MIT License - see [LICENSE](LICENSE) for details.