gitwebhooks 2.0.0__tar.gz → 2.1.0__tar.gz

{gitwebhooks-2.0.0 → gitwebhooks-2.1.0}/CLAUDE.md

@@ -15,13 +15,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 常用命令
 
-### 安装和卸载
+### 安装和配置
 ```bash
-# 安装（交互式）
-./install.sh
+# 通过 pip 安装
+pip install .
 
-# 卸载
-./install.sh --uninstall
+# 初始化配置文件（交互式）
+gitwebhooks-cli config init
+
+# 直接指定配置级别（system/local/user）
+gitwebhooks-cli config init user
+sudo gitwebhooks-cli config init system
+
+# 查看配置文件内容
+gitwebhooks-cli config view
+
+# 安装为 systemd 服务
+sudo gitwebhooks-cli service install
+
+# 卸载 systemd 服务
+sudo gitwebhooks-cli service uninstall
 ```
 
 ### 运行服务
@@ -29,7 +42,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # 方式1: 使用模块入口
 python3 -m gitwebhooks.cli -c /path/to/config.ini
 
-# 方式2: 使用 CLI 工具（安装后）
+# 方式2: 使用 CLI 工具（使用默认配置）
+gitwebhooks-cli
+
+# 方式3: 指定配置文件
 gitwebhooks-cli -c /path/to/config.ini
 
 # systemd 服务管理
@@ -66,12 +82,25 @@ python3 -m pytest tests/
 - `config/`: 配置加载和注册（ConfigLoader、ConfigurationRegistry）
 - `auth/`: 签名验证模块（各平台的验证器工厂）
 - `handlers/`: Webhook 处理器（按平台分离的处理器）
-- `utils/`: 工具类（常量、异常、命令执行器）
+- `utils/`: 工具类（常量、异常、命令执行器、systemd 工具）
+- `cli/`: CLI 子命令（service、config、init_wizard）
+  - `service.py`: systemd 服务管理
+  - `config.py`: 配置查看和管理
+  - `init_wizard.py`: 交互式配置初始化向导
 - `logging/`: 日志配置
 
 **CLI 工具** (`gitwebhooks-cli`)
 - Bash 包装脚本，自动检测并加载 `gitwebhooks` 包
 - 支持从源码目录运行或已安装的包运行
+- 支持子命令：
+  - `gitwebhooks-cli service install/uninstall`: systemd 服务管理
+  - `gitwebhooks-cli config init [level]`: 交互式配置初始化向导
+    - 支持配置级别：`system`（系统级，需 root）、`local`（本地级，需 root）、`user`（用户级）
+    - 交互式收集服务器配置、平台配置（github/gitee/gitlab/custom）、仓库配置
+    - 自动生成 INI 配置文件，设置安全权限（0600）
+    - 支持配置文件覆盖和备份
+  - `gitwebhooks-cli config view`: 查看配置文件内容
+  - `gitwebhooks-cli -c <config>`: 运行服务器（兼容原有方式）
 
 **Provider 枚举** (`gitwebhooks/models/provider.py`)
 - 定义支持的 Git 平台：Github、Gitee、Gitlab、Custom
@@ -253,6 +282,17 @@ git-webhooks-server/
 - ssl (HTTPS 支持)
 - pytest (测试框架)
 - Bash 4.0+ (安装脚本)
+- Python 3.6+ (与项目一致) + Python 标准库（argparse 用于子命令，tempfile 用于文件操作，pathlib 用于路径处理） (001-cli-service-install)
+- INI 配置文件（`~/.gitwebhook.ini`），systemd 服务文件（`/etc/systemd/system/`） (001-cli-service-install)
+- Python 3.7+ (与项目保持一致) + Python 标准库（configparser、pathlib、os、sys） (001-config-view)
+- INI 配置文件（只读） (001-config-view)
+- Python 3.7+ + Python 标准库（dataclasses、configparser、os、re、sys） + 交互式 input() (001-config-init-wizard)
+- INI 配置文件生成（读写） (001-config-init-wizard)
+- Python 3.7+ + Python 标准库（sys, shutil, os, pathlib, argparse） (001-install-method-guidance)
+- INI 配置文件，systemd 服务单元文件 (001-install-method-guidance)
 
 ## Recent Changes
+- 001-config-init-wizard: 添加 `config init` 交互式向导，支持配置级别选择、平台配置和仓库配置
+- 001-config-view: 添加 `config view` 子命令，支持查看配置文件内容和敏感字段高亮
+- 001-cli-service-install: 添加 systemd 服务管理子命令（install/uninstall）
 - 001-refactor-codebase: 重构为模块化包结构，保持向后兼容

{gitwebhooks-2.0.0 → gitwebhooks-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwebhooks
-Version: 2.0.0
+Version: 2.1.0
 Summary: A lightweight Git webhook server for automated deployment supporting GitHub, Gitee, GitLab, and custom webhooks
 Author-email: Troy Tse <troy@holyhi.net>
 Maintainer-email: Troy Tse <troy@holyhi.net>
@@ -90,29 +90,112 @@ gitwebhooks/
 ### Prerequisites
 
 - Python 3.6 or higher
-- sudo/root access (for installation)
+- pip (Python package manager)
+- sudo/root access (for systemd service installation)
 
-### Install from Source
+### Recommended: pipx (System-wide installation)
+
+pipx is the recommended way to install git-webhooks-server system-wide.
 
 ```bash
-# Clone or download the repository
-git clone https://github.com/troytse/git-webhooks-server.git
-cd git-webhooks-server
+# Install pipx (if not already installed)
+sudo apt install pipx  # Ubuntu/Debian
+# or: python3 -m pip install --user pipx
 
-# Run the installation script
-./install.sh
+# Install git-webhooks-server
+pipx install git-webhooks-server
 ```
 
-The installer will:
-1. Create a hard link for `gitwebhooks-cli` in `/usr/local/bin`
-2. Copy configuration file to `/usr/local/etc/git-webhooks-server.ini`
-3. Optionally install as a systemd service
+**Why pipx?**
+- Isolated from system Python packages
+- No dependency conflicts
+- Easy to upgrade and uninstall
+- Automatic service file configuration
+
+### Alternative: venv (Virtual environment)
+
+If you prefer using Python's built-in venv module:
+
+```bash
+# Create virtual environment
+python3 -m venv ~/venv/gitwebhooks
+
+# Activate and install
+source ~/venv/gitwebhooks/bin/activate
+pip install git-webhooks-server
+
+# Add to PATH (optional)
+echo 'export PATH="$HOME/venv/gitwebhooks/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### ⚠️ NOT Recommended: System pip
+
+**Warning**: Installing directly with `sudo pip install` is NOT recommended:
+
+```bash
+# DO NOT DO THIS
+sudo pip install git-webhooks-server
+```
+
+**Risks**:
+- Can conflict with system Python packages
+- May break system tools that depend on Python
+- Difficult to uninstall cleanly
+
+### Initialize Configuration
+
+```bash
+# Interactive configuration setup (prompts for configuration level)
+gitwebhooks-cli config init
+
+# Or specify configuration level directly
+gitwebhooks-cli config init user      # User level (~/.gitwebhooks.ini)
+gitwebhooks-cli config init local      # Local level (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli config init system # System level (/etc/gitwebhooks.ini, requires root)
+```
+
+The wizard will prompt for:
+1. Configuration level (system/local/user)
+2. Server configuration (address, port, log file)
+3. Git platform (github/gitee/gitlab/custom)
+4. Platform-specific settings (webhook events, verification, secret)
+5. Repository configuration (name, working directory, deploy command)
+
+This will create a configuration file with secure permissions (0600).
 
-![install](doc/install.png)
+### Install as systemd Service
+
+The service installation command automatically detects your installation type (pipx, venv, or system) and generates the appropriate service file.
+
+```bash
+# Install and start as a systemd service
+sudo gitwebhooks-cli service install
+
+# Preview service file without installing (dry-run mode)
+sudo gitwebhooks-cli service install --dry-run
+
+# Install with verbose output
+sudo gitwebhooks-cli service install --verbose
+sudo gitwebhooks-cli service install -v      # Basic verbosity
+sudo gitwebhooks-cli service install -vv     # Extra verbosity
+
+# Force overwrite existing service
+sudo gitwebhooks-cli service install --force
+
+# Uninstall the service
+sudo gitwebhooks-cli service uninstall
+```
+
+**Service file auto-detection**:
+- **pipx installation**: Uses `gitwebhooks-cli` command directly
+- **venv/virtualenv**: Uses `python -m gitwebhooks.cli` with environment's Python
+- **System pip**: Uses system Python with `python -m gitwebhooks.cli`
+- **conda**: Not supported - installation will be refused with clear error message
 
 ### Manual Installation
 
-To install manually without the script:
+To install manually without pip:
 
 ```bash
 # Make CLI executable
@@ -120,9 +203,6 @@ chmod +x gitwebhooks-cli
 
 # Create hard link to system path
 sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
-
-# Copy configuration
-sudo cp git-webhooks-server.ini.sample /usr/local/etc/git-webhooks-server.ini
 ```
 
 ### Verify Installation
@@ -131,20 +211,89 @@ sudo cp git-webhooks-server.ini.sample /usr/local/etc/git-webhooks-server.ini
 gitwebhooks-cli --help
 ```
 
-## Uninstallation
+## Migrating from System pip Installation
+
+If you previously installed git-webhooks-server using `sudo pip install`,
+follow these steps to migrate to a recommended installation method.
+
+### Step 1: Uninstall the old installation
+
+```bash
+sudo pip uninstall git-webhooks-server
+```
+
+### Step 2: Backup your configuration (if exists)
+
+```bash
+cp ~/.gitwebhook.ini ~/.gitwebhook.ini.backup
+```
+
+### Step 3: Stop and uninstall the service (if installed)
 
 ```bash
-cd git-webhooks-server
-./install.sh --uninstall
+sudo systemctl stop git-webhooks-server
+sudo systemctl disable git-webhooks-server
+sudo gitwebhooks-cli service uninstall
 ```
 
-![uninstall](doc/uninstall.png)
+### Step 4: Install using the recommended method
+
+Choose **pipx** (recommended):
+```bash
+# Install pipx if needed
+sudo apt install pipx  # Ubuntu/Debian
+# or: python3 -m pip install --user pipx
+
+# Install git-webhooks-server
+pipx install git-webhooks-server
+```
+
+Or **venv**:
+```bash
+# Create virtual environment
+python3 -m venv ~/venv/gitwebhooks
+source ~/venv/gitwebhooks/bin/activate
+
+# Install git-webhooks-server
+pip install git-webhooks-server
+```
+
+### Step 5: Restore configuration (if backed up)
+
+```bash
+# If you backed up your configuration
+cp ~/.gitwebhook.ini.backup ~/.gitwebhook.ini
+# Or create a new one
+gitwebhooks-cli config init
+```
+
+### Step 6: Reinstall the service
+
+```bash
+sudo gitwebhooks-cli service install
+```
+
+### Step 7: Verify
+
+```bash
+sudo systemctl status git-webhooks-server
+```
+
+## Uninstallation
+
+```bash
+# Uninstall systemd service (if installed)
+sudo gitwebhooks-cli service uninstall --purge
+
+# Remove the package
+pip uninstall gitwebhooks
+```
 
 ## Usage
 
 ### 1. Configure Repository
 
-Edit `/usr/local/etc/git-webhooks-server.ini`:
+Edit `~/.gitwebhook.ini`:
 
 ```ini
 [your_name/repository]
@@ -155,9 +304,11 @@ cmd=git fetch --all && git reset --hard origin/master && git pull
 ### 2. Restart Service
 
 ```bash
+# If running as a service
 systemctl restart git-webhooks-server
+
 # Or run directly:
-gitwebhooks-cli -c /usr/local/etc/git-webhooks-server.ini
+gitwebhooks-cli
 ```
 
 ### 3. Add Webhook
@@ -211,7 +362,38 @@ Example payload:
 
 ## Configuration
 
-Default configuration file: `/usr/local/etc/git-webhooks-server.ini`
+Default configuration file: `~/.gitwebhook.ini`
+
+### Initialize Configuration
+
+```bash
+# Interactive configuration setup
+gitwebhooks-cli config init
+
+# Or specify configuration level directly
+gitwebhooks-cli config init user
+sudo gitwebhooks-cli config init system
+```
+
+### View Configuration
+
+```bash
+# View current configuration file (auto-detects location)
+gitwebhooks-cli config view
+
+# View specific configuration file
+gitwebhooks-cli config view -c /path/to/config.ini
+```
+
+The `config view` command displays:
+- Configuration file path and source (user-specified or auto-detected)
+- Configuration content organized by sections
+- Sensitive fields (containing: secret, password, token, key, passphrase) highlighted in yellow
+
+To disable color highlighting:
+```bash
+NO_COLOR=1 gitwebhooks-cli config view
+```
 
 ### Server Configuration
 
@@ -219,7 +401,7 @@ Default configuration file: `/usr/local/etc/git-webhooks-server.ini`
 [server]
 address=0.0.0.0          # Listen address
 port=6789                # Listen port
-log_file=/var/log/git-webhooks-server.log  # Log file (empty = stdout only)
+log_file=~/.gitwebhook.log  # Log file (empty = stdout only)
 ```
 
 ### SSL Configuration (Optional)