gitwebhooks 2.1.4__tar.gz → 2.3.0__tar.gz

{gitwebhooks-2.1.4 → gitwebhooks-2.3.0}/CLAUDE.md

@@ -42,7 +42,7 @@ sudo gitwebhooks-cli service uninstall
 # 方式1: 使用模块入口
 python3 -m gitwebhooks.cli -c /path/to/config.ini
 
-# 方式2: 使用 CLI 工具（使用默认配置）
+# 方式2: 使用 CLI 工具（自动查找配置文件）
 gitwebhooks-cli
 
 # 方式3: 指定配置文件
@@ -55,6 +55,14 @@ systemctl restart gitwebhooks
 systemctl status gitwebhooks
 ```
 
+**配置文件自动查找**：
+- 不指定 `-c` 参数时，系统按优先级自动查找配置文件：
+  1. `~/.gitwebhooks.ini`（用户级，最高优先级）
+  2. `/usr/local/etc/gitwebhooks.ini`（本地级）
+  3. `/etc/gitwebhooks.ini`（系统级）
+- 启动时会显示正在使用的配置文件路径
+- 找不到配置文件时显示友好的错误消息
+
 ### 测试开发
 ```bash
 # 直接运行（开发模式）
@@ -292,6 +300,11 @@ gitwebhooks/
 - INI 配置文件，systemd 服务单元文件 (001-install-method-guidance)
 - Python 3.7+ (项目要求) + Python 标准库仅（无外部依赖） (001-fix-config-init-bug)
 - INI 配置文件 (configparser) (001-fix-config-init-bug)
+- Python 3.7+ (项目要求) + Python 标准库（pathlib, configparser, argparse） (001-config-priority)
+- Python 3.6+ (与项目要求一致，实际支持 3.6-3.14) + argparse (Python 标准库) (002-cli-commands-refactor)
+- N/A (CLI 重构，不涉及存储) (002-cli-commands-refactor)
+- Python 3.6+（项目要求），实际支持 3.6-3.14 + Python 标准库 `argparse`（命令行参数解析） (002-cli-commands-refactor)
+- N/A（CLI 重构，不涉及存储） (002-cli-commands-refactor)
 
 ## Recent Changes
 - 001-config-init-wizard: 添加 `config init` 交互式向导，支持配置级别选择、平台配置和仓库配置

{gitwebhooks-2.1.4 → gitwebhooks-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwebhooks
-Version: 2.1.4
+Version: 2.3.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>
@@ -169,28 +169,40 @@ This will create a configuration file with secure permissions (0600).
 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
+# Install and start as a systemd service (interactive config level selection)
+sudo gitwebhooks-cli serve install
+
+# Install with specific config level (skip interactive selection)
+sudo gitwebhooks-cli serve install --config-level user    # User level (~/.gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level local   # Local level (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level system   # System level (/etc/gitwebhooks.ini)
+
+# Use custom config file (backward compatibility)
+sudo gitwebhooks-cli serve install -c /path/to/config.ini
 
 # Preview service file without installing (dry-run mode)
-sudo gitwebhooks-cli service install --dry-run
+sudo gitwebhooks-cli serve install --dry-run
+sudo gitwebhooks-cli serve install --config-level local --dry-run  # Preview specific level
 
 # 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
+sudo gitwebhooks-cli serve install --verbose
 
 # Force overwrite existing service
-sudo gitwebhooks-cli service install --force
+sudo gitwebhooks-cli serve install --force
 
 # Uninstall the service
-sudo gitwebhooks-cli service uninstall
+sudo gitwebhooks-cli serve uninstall
 ```
 
+**Configuration levels**:
+- **user**: `~/.gitwebhooks.ini` - Single user configuration, highest priority
+- **local**: `/usr/local/etc/gitwebhooks.ini` - Local system configuration, medium priority
+- **system**: `/etc/gitwebhooks.ini` - Global system configuration, lowest priority
+
 **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`
+- **venv/virtualenv**: Uses `python -m gitwebhooks.main` with environment's Python
+- **System pip**: Uses system Python with `python -m gitwebhooks.main`
 - **conda**: Not supported - installation will be refused with clear error message
 
 ### Manual Installation
@@ -208,7 +220,14 @@ sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
 ### Verify Installation
 
 ```bash
-gitwebhooks-cli --help
+# Show version
+gitwebhooks-cli -v
+
+# Show help
+gitwebhooks-cli help
+
+# View configuration
+gitwebhooks-cli config view
 ```
 
 ## Migrating from System pip Installation
@@ -291,9 +310,47 @@ pip uninstall gitwebhooks
 
 ## Usage
 
+### Configuration File Auto-Discovery
+
+The `gitwebhooks-cli` automatically searches for configuration files in the following order (priority):
+
+1. **User level**: `~/.gitwebhooks.ini` (highest priority)
+2. **Local level**: `/usr/local/etc/gitwebhooks.ini`
+3. **System level**: `/etc/gitwebhooks.ini` (lowest priority)
+
+You can run `gitwebhooks-cli` without specifying `-c` parameter, and it will automatically use the first existing configuration file.
+
+```bash
+# Auto-discover and use configuration file
+gitwebhooks-cli
+
+# The server will display which config file is being used
+# Using configuration file: /home/user/.gitwebhooks.ini
+```
+
+If you want to use a specific configuration file, use the `-c` parameter:
+
+```bash
+# Use a specific configuration file
+gitwebhooks-cli -c /path/to/custom.ini
+```
+
+If no configuration file is found, a friendly error message will display all searched paths:
+
+```
+Error: Configuration file not found.
+Searched paths:
+  1. /home/user/.gitwebhooks.ini
+  2. /usr/local/etc/gitwebhooks.ini
+  3. /etc/gitwebhooks.ini
+
+You can create a configuration file using:
+  gitwebhooks-cli config init
+```
+
 ### 1. Configure Repository
 
-Edit `~/.gitwebhook.ini`:
+Edit your configuration file (e.g., `~/.gitwebhooks.ini`):
 
 ```ini
 [your_name/repository]
@@ -307,7 +364,7 @@ cmd=git fetch --all && git reset --hard origin/master && git pull
 # If running as a service
 systemctl restart gitwebhooks
 
-# Or run directly:
+# Or run directly (auto-discovers config file):
 gitwebhooks-cli
 ```
 

{gitwebhooks-2.1.4 → gitwebhooks-2.3.0}/README.md

@@ -129,28 +129,40 @@ This will create a configuration file with secure permissions (0600).
 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
+# Install and start as a systemd service (interactive config level selection)
+sudo gitwebhooks-cli serve install
+
+# Install with specific config level (skip interactive selection)
+sudo gitwebhooks-cli serve install --config-level user    # User level (~/.gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level local   # Local level (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level system   # System level (/etc/gitwebhooks.ini)
+
+# Use custom config file (backward compatibility)
+sudo gitwebhooks-cli serve install -c /path/to/config.ini
 
 # Preview service file without installing (dry-run mode)
-sudo gitwebhooks-cli service install --dry-run
+sudo gitwebhooks-cli serve install --dry-run
+sudo gitwebhooks-cli serve install --config-level local --dry-run  # Preview specific level
 
 # 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
+sudo gitwebhooks-cli serve install --verbose
 
 # Force overwrite existing service
-sudo gitwebhooks-cli service install --force
+sudo gitwebhooks-cli serve install --force
 
 # Uninstall the service
-sudo gitwebhooks-cli service uninstall
+sudo gitwebhooks-cli serve uninstall
 ```
 
+**Configuration levels**:
+- **user**: `~/.gitwebhooks.ini` - Single user configuration, highest priority
+- **local**: `/usr/local/etc/gitwebhooks.ini` - Local system configuration, medium priority
+- **system**: `/etc/gitwebhooks.ini` - Global system configuration, lowest priority
+
 **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`
+- **venv/virtualenv**: Uses `python -m gitwebhooks.main` with environment's Python
+- **System pip**: Uses system Python with `python -m gitwebhooks.main`
 - **conda**: Not supported - installation will be refused with clear error message
 
 ### Manual Installation
@@ -168,7 +180,14 @@ sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
 ### Verify Installation
 
 ```bash
-gitwebhooks-cli --help
+# Show version
+gitwebhooks-cli -v
+
+# Show help
+gitwebhooks-cli help
+
+# View configuration
+gitwebhooks-cli config view
 ```
 
 ## Migrating from System pip Installation
@@ -251,9 +270,47 @@ pip uninstall gitwebhooks
 
 ## Usage
 
+### Configuration File Auto-Discovery
+
+The `gitwebhooks-cli` automatically searches for configuration files in the following order (priority):
+
+1. **User level**: `~/.gitwebhooks.ini` (highest priority)
+2. **Local level**: `/usr/local/etc/gitwebhooks.ini`
+3. **System level**: `/etc/gitwebhooks.ini` (lowest priority)
+
+You can run `gitwebhooks-cli` without specifying `-c` parameter, and it will automatically use the first existing configuration file.
+
+```bash
+# Auto-discover and use configuration file
+gitwebhooks-cli
+
+# The server will display which config file is being used
+# Using configuration file: /home/user/.gitwebhooks.ini
+```
+
+If you want to use a specific configuration file, use the `-c` parameter:
+
+```bash
+# Use a specific configuration file
+gitwebhooks-cli -c /path/to/custom.ini
+```
+
+If no configuration file is found, a friendly error message will display all searched paths:
+
+```
+Error: Configuration file not found.
+Searched paths:
+  1. /home/user/.gitwebhooks.ini
+  2. /usr/local/etc/gitwebhooks.ini
+  3. /etc/gitwebhooks.ini
+
+You can create a configuration file using:
+  gitwebhooks-cli config init
+```
+
 ### 1. Configure Repository
 
-Edit `~/.gitwebhook.ini`:
+Edit your configuration file (e.g., `~/.gitwebhooks.ini`):
 
 ```ini
 [your_name/repository]
@@ -267,7 +324,7 @@ cmd=git fetch --all && git reset --hard origin/master && git pull
 # If running as a service
 systemctl restart gitwebhooks
 
-# Or run directly:
+# Or run directly (auto-discovers config file):
 gitwebhooks-cli
 ```
 

{gitwebhooks-2.1.4 → gitwebhooks-2.3.0}/README.zh.md

@@ -129,28 +129,40 @@ sudo gitwebhooks-cli config init system # 系统级（/etc/gitwebhooks.ini，需
 服务安装命令会自动检测您的安装类型（pipx、venv 或系统）并生成相应的服务文件。
 
 ```bash
-# 安装并启动为 systemd 服务
-sudo gitwebhooks-cli service install
+# 安装并启动为 systemd 服务（交互式选择配置级别）
+sudo gitwebhooks-cli serve install
+
+# 使用指定配置级别安装（跳过交互式选择）
+sudo gitwebhooks-cli serve install --config-level user    # 用户级配置 (~/.gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level local   # 本地级配置 (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level system   # 系统级配置 (/etc/gitwebhooks.ini)
+
+# 使用自定义配置文件（向后兼容）
+sudo gitwebhooks-cli serve install -c /path/to/config.ini
 
 # 预览服务文件但不安装（dry-run 模式）
-sudo gitwebhooks-cli service install --dry-run
+sudo gitwebhooks-cli serve install --dry-run
+sudo gitwebhooks-cli serve install --config-level local --dry-run  # 预览指定级别的配置
 
 # 安装并显示详细输出
-sudo gitwebhooks-cli service install --verbose
-sudo gitwebhooks-cli service install -v      # 基本详细程度
-sudo gitwebhooks-cli service install -vv     # 额外详细程度
+sudo gitwebhooks-cli serve install --verbose
 
 # 强制覆盖现有服务
-sudo gitwebhooks-cli service install --force
+sudo gitwebhooks-cli serve install --force
 
 # 卸载服务
-sudo gitwebhooks-cli service uninstall
+sudo gitwebhooks-cli serve uninstall
 ```
 
+**配置级别说明**：
+- **user（用户级）**：`~/.gitwebhooks.ini` - 单用户配置，最高优先级
+- **local（本地级）**：`/usr/local/etc/gitwebhooks.ini` - 本地系统配置，中等优先级
+- **system（系统级）**：`/etc/gitwebhooks.ini` - 全局系统配置，最低优先级
+
 **服务文件自动检测**：
 - **pipx 安装**：直接使用 `gitwebhooks-cli` 命令
-- **venv/virtualenv**：使用环境的 Python 执行 `python -m gitwebhooks.cli`
-- **系统 pip**：使用系统 Python 执行 `python -m gitwebhooks.cli`
+- **venv/virtualenv**：使用环境的 Python 执行 `python -m gitwebhooks.main`
+- **系统 pip**：使用系统 Python 执行 `python -m gitwebhooks.main`
 - **conda**：不支持 - 安装将被拒绝并显示明确错误消息
 
 ### 手动安装
@@ -168,7 +180,14 @@ sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
 ### 验证安装
 
 ```bash
-gitwebhooks-cli --help
+# 显示版本
+gitwebhooks-cli -v
+
+# 显示帮助
+gitwebhooks-cli help
+
+# 查看配置
+gitwebhooks-cli config view
 ```
 
 ## 从系统 pip 安装迁移
@@ -251,9 +270,47 @@ pip uninstall gitwebhooks
 
 ## 使用
 
+### 配置文件自动查找
+
+`gitwebhooks-cli` 会自动按以下顺序（优先级）搜索配置文件：
+
+1. **用户级**：`~/.gitwebhooks.ini`（最高优先级）
+2. **本地级**：`/usr/local/etc/gitwebhooks.ini`
+3. **系统级**：`/etc/gitwebhooks.ini`（最低优先级）
+
+您可以直接运行 `gitwebhooks-cli` 而无需指定 `-c` 参数，系统会自动使用第一个存在的配置文件。
+
+```bash
+# 自动查找并使用配置文件
+gitwebhooks-cli
+
+# 服务器会显示正在使用的配置文件
+# Using configuration file: /home/user/.gitwebhooks.ini
+```
+
+如果需要使用特定的配置文件，可以使用 `-c` 参数：
+
+```bash
+# 使用指定的配置文件
+gitwebhooks-cli -c /path/to/custom.ini
+```
+
+如果找不到配置文件，会显示友好的错误消息并列出所有搜索路径：
+
+```
+Error: Configuration file not found.
+Searched paths:
+  1. /home/user/.gitwebhooks.ini
+  2. /usr/local/etc/gitwebhooks.ini
+  3. /etc/gitwebhooks.ini
+
+You can create a configuration file using:
+  gitwebhooks-cli config init
+```
+
 ### 1. 配置仓库
 
-编辑 `~/.gitwebhook.ini`：
+编辑您的配置文件（例如 `~/.gitwebhooks.ini`）：
 
 ```ini
 [your_name/repository]
@@ -267,7 +324,7 @@ cmd=git fetch --all && git reset --hard origin/master && git pull
 # 如果作为服务运行
 systemctl restart gitwebhooks
 
-# 或直接运行：
+# 或直接运行（自动查找配置文件）：
 gitwebhooks-cli
 ```
 

{gitwebhooks-2.1.4 → gitwebhooks-2.3.0}/gitwebhooks/__init__.py

@@ -3,7 +3,7 @@
 Automated deployment server supporting GitHub, Gitee, GitLab, and custom webhooks.
 """
 
-__version__ = '2.0.0'
+__version__ = '2.3.0'
 
 # Export main classes for convenient import paths
 from .server import WebhookServer

gitwebhooks-2.3.0/gitwebhooks/cli/__init__.py

@@ -0,0 +1,203 @@
+"""CLI subcommands module
+
+Provides subcommand registration and implementation for gitwebhooks-cli.
+"""
+
+from gitwebhooks.cli.service import cmd_install, cmd_uninstall
+from gitwebhooks.cli.config import cmd_init, cmd_view
+from gitwebhooks.cli.help import cmd_help
+from gitwebhooks.cli.serve import cmd_serve
+
+
+def register_subparsers(subparsers):
+    """Register all CLI subparsers
+
+    Args:
+        subparsers: argparse subparsers object from ArgumentParser.add_subparsers()
+
+    Returns:
+        None
+    """
+    # Register help subcommand
+    register_help_subparser(subparsers)
+
+    # Register serve subcommand
+    register_serve_subparser(subparsers)
+
+    # Register config subcommand
+    register_config_subparser(subparsers)
+
+    # Register service subcommand (deprecated, for backward compatibility)
+    register_service_subparser(subparsers)
+
+
+def register_serve_subparser(subparsers):
+    """Register serve subcommand and its actions
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    serve_parser = subparsers.add_parser(
+        'serve',
+        add_help=False,
+        help='Start webhook server or manage systemd service'
+    )
+    serve_parser.add_argument(
+        '-c', '--config',
+        dest='config',
+        help='Path to configuration file (default: auto-discover)'
+    )
+    serve_subparsers = serve_parser.add_subparsers(dest='serve_action')
+
+    # install action
+    install_parser = serve_subparsers.add_parser('install', add_help=False)
+    install_parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force overwrite existing service'
+    )
+    install_parser.add_argument(
+        '--verbose',
+        action='count',
+        default=0,
+        help='Increase verbosity'
+    )
+    install_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview mode without making changes'
+    )
+    install_parser.add_argument(
+        '--config-level',
+        choices=['user', 'local', 'system'],
+        help='Configuration file level (user/local/system)'
+    )
+    install_parser.set_defaults(func=cmd_serve)
+
+    # uninstall action
+    uninstall_parser = serve_subparsers.add_parser('uninstall', add_help=False)
+    uninstall_parser.add_argument(
+        '--purge',
+        action='store_true',
+        help='Also remove configuration file'
+    )
+    uninstall_parser.set_defaults(func=cmd_serve)
+
+    # Set default function for serve (when no action specified)
+    serve_parser.set_defaults(func=cmd_serve)
+
+
+def register_help_subparser(subparsers):
+    """Register help subcommand
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    help_parser = subparsers.add_parser(
+        'help',
+        add_help=False
+    )
+    help_parser.add_argument(
+        'topic',
+        nargs='?',
+        help='Subcommand to show help for (serve, config)'
+    )
+    help_parser.set_defaults(func=cmd_help)
+
+
+def register_service_subparser(subparsers):
+    """Register service subcommand and its actions (deprecated)
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    service_parser = subparsers.add_parser(
+        'service',
+        add_help=False,
+        help='Manage systemd service installation (deprecated, use "serve" instead)'
+    )
+    service_subparsers = service_parser.add_subparsers(dest='service_action')
+
+    # install action
+    install_parser = service_subparsers.add_parser('install', add_help=False)
+    install_parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force overwrite existing service'
+    )
+    install_parser.add_argument(
+        '-v', '--verbose',
+        action='count',
+        default=0,
+        help='Increase verbosity (can be used: -v, -vv)'
+    )
+    install_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview service file without installing'
+    )
+    install_parser.add_argument(
+        '--config-level',
+        choices=['user', 'local', 'system'],
+        help='Configuration file level (user/local/system). If not specified, will be prompted.'
+    )
+    install_parser.set_defaults(func=cmd_install)
+
+    # uninstall action
+    uninstall_parser = service_subparsers.add_parser('uninstall', add_help=False)
+    uninstall_parser.add_argument(
+        '--purge',
+        action='store_true',
+        help='Also remove configuration file'
+    )
+    uninstall_parser.set_defaults(func=cmd_uninstall)
+
+
+def register_config_subparser(subparsers):
+    """Register config subcommand and its actions
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    config_parser = subparsers.add_parser(
+        'config',
+        add_help=False,
+        help='Manage gitwebhooks configuration'
+    )
+    config_subparsers = config_parser.add_subparsers(dest='config_action')
+
+    # init action
+    init_parser = config_subparsers.add_parser(
+        'init',
+        add_help=False,
+        help='Initialize configuration file using interactive wizard'
+    )
+    init_parser.add_argument(
+        'level',
+        nargs='?',
+        choices=['system', 'local', 'user'],
+        help='Configuration level (system/local/user). If not specified, will be prompted.'
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # view action
+    view_parser = config_subparsers.add_parser('view', add_help=False)
+    view_parser.add_argument(
+        '-c',
+        '--config',
+        dest='config',
+        help='Path to configuration file (default: auto-detect)'
+    )
+    view_parser.set_defaults(func=cmd_view)