gitwebhooks 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -301,6 +301,10 @@ gitwebhooks/
 - 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.2.0 → gitwebhooks-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwebhooks
-Version: 2.2.0
+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

{gitwebhooks-2.2.0 → 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

{gitwebhooks-2.2.0 → 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 安装迁移

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

@@ -3,7 +3,7 @@
 Automated deployment server supporting GitHub, Gitee, GitLab, and custom webhooks.
 """
 
-__version__ = '2.2.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)

gitwebhooks-2.3.0/gitwebhooks/cli/help.py

@@ -0,0 +1,155 @@
+"""Help command module
+
+Provides help information display functionality for gitwebhooks-cli.
+"""
+
+import argparse
+import sys
+
+
+def cmd_help(args: argparse.Namespace) -> int:
+    """Handle help subcommand.
+
+    Displays main help or subcommand-specific help depending on the topic.
+
+    Args:
+        args: Parsed command-line arguments
+            - topic: Optional subcommand name to show help for
+
+    Returns:
+        Exit code (0 = success)
+
+    Examples:
+        >>> args = argparse.Namespace(topic=None)
+        >>> cmd_help(args)  # doctest: +SKIP
+        0
+        >>> args = argparse.Namespace(topic='serve')
+        >>> cmd_help(args)  # doctest: +SKIP
+        0
+    """
+    # Import here to avoid circular dependency
+    from gitwebhooks.main import get_parser
+
+    parser = get_parser()
+
+    if hasattr(args, 'topic') and args.topic:
+        # Show subcommand help
+        show_subcommand_help(parser, args.topic)
+    else:
+        # Show main help
+        show_main_help(parser)
+
+    return 0
+
+
+def show_main_help(parser: argparse.ArgumentParser) -> None:
+    """Display main help information.
+
+    Args:
+        parser: The main argument parser
+
+    Returns:
+        None
+    """
+    # Custom help output
+    help_text = """Git Webhooks Server - Automated deployment webhook handler
+
+Usage:
+  gitwebhooks-cli [-v] [-c CONFIG] <command> [<args>]
+
+Commands:
+  serve       Start webhook server or manage systemd service
+  config      Manage configuration file
+  help        Show help information
+
+Options:
+  -v, --version  Show version information
+  -c, --config   Path to configuration file (default: auto-discover)
+
+Examples:
+  gitwebhooks-cli serve                    # Start server
+  gitwebhooks-cli serve install            # Install systemd service
+  gitwebhooks-cli config init              # Initialize configuration
+  gitwebhooks-cli help serve               # Show serve command help
+
+For more information on a specific command:
+  gitwebhooks-cli help <command>
+"""
+    print(help_text)
+
+
+def show_subcommand_help(parser: argparse.ArgumentParser, topic: str) -> None:
+    """Display help for a specific subcommand.
+
+    Args:
+        parser: The main argument parser
+        topic: Subcommand name
+
+    Returns:
+        None
+    """
+    # Map topic to help text
+    help_texts = {
+        'serve': """Command: serve
+Start webhook server or manage systemd service
+
+Usage:
+  gitwebhooks-cli serve [-c CONFIG]
+  gitwebhooks-cli serve install [--force] [--dry-run] [--verbose]
+  gitwebhooks-cli serve uninstall [--purge]
+
+Subcommands:
+  (none)        Start the webhook server
+  install       Install systemd service
+  uninstall     Uninstall systemd service
+
+Options:
+  -c, --config   Path to configuration file
+
+Install options:
+  --force        Force overwrite existing service
+  --dry-run      Preview mode, don't make changes
+  --verbose      Increase verbosity
+
+Uninstall options:
+  --purge        Also remove configuration file
+
+Examples:
+  gitwebhooks-cli serve                         # Start server
+  gitwebhooks-cli serve -c /etc/webhooks.ini    # Start with custom config
+  gitwebhooks-cli serve install                 # Install service
+  gitwebhooks-cli serve install --force         # Force overwrite
+  gitwebhooks-cli serve uninstall               # Uninstall service
+""",
+        'config': """Command: config
+Manage configuration file
+
+Usage:
+  gitwebhooks-cli config init [level]
+  gitwebhooks-cli config view [-c CONFIG]
+
+Subcommands:
+  init          Initialize configuration file
+  view          View configuration file
+
+Init arguments:
+  level         Configuration level (system, local, user)
+
+View options:
+  -c, --config  Path to configuration file
+
+Examples:
+  gitwebhooks-cli config init              # Interactive init
+  gitwebhooks-cli config init user         # User-level config
+  gitwebhooks-cli config init system       # System-level config (requires sudo)
+  gitwebhooks-cli config view              # View current config
+""",
+    }
+
+    if topic in help_texts:
+        print(help_texts[topic])
+    else:
+        print(f"Error: Unknown command '{topic}'", file=sys.stderr)
+        print("Available commands: serve, config", file=sys.stderr)
+        print()
+        print("Use 'gitwebhooks-cli help' to see main help", file=sys.stderr)

{gitwebhooks-2.2.0 → gitwebhooks-2.3.0}/gitwebhooks/cli/prompts.py

@@ -4,7 +4,9 @@ Provides functions for interactive user input and validation.
 """
 
 import sys
-from typing import Any, Callable, Optional, Dict, List
+from typing import Any, Callable, Optional, Dict, List, Tuple
+
+from gitwebhooks.utils.constants import ConfigLevel
 
 
 # Question template for configuration initialization
@@ -273,3 +275,48 @@ def validate_text(value: str) -> str:
     if not value:
         raise ValueError('Input cannot be empty')
     return value
+
+
+def ask_config_level() -> ConfigLevel:
+    """Ask user to select configuration file level
+
+    Displays an interactive menu for selecting configuration file level
+    with descriptions of each option.
+
+    Returns:
+        Selected ConfigLevel enum value
+
+    Raises:
+        KeyboardInterrupt: If user confirms exit on Ctrl+C
+    """
+    print('Select configuration file level for the service:')
+    print('  1. User level (~/.gitwebhooks.ini) - Single user, highest priority')
+    print('  2. Local level (/usr/local/etc/gitwebhooks.ini) - Local system, medium priority')
+    print('  3. System level (/etc/gitwebhooks.ini) - Global system, lowest priority')
+    print()
+
+    choice_map = {
+        '1': ConfigLevel.USER,
+        '2': ConfigLevel.LOCAL,
+        '3': ConfigLevel.SYSTEM,
+    }
+
+    while True:
+        try:
+            response = input('Enter choice [1-3] (default: 1): ').strip()
+
+            # Use default if empty input
+            if not response:
+                return ConfigLevel.USER
+
+            # Validate and map response
+            if response in choice_map:
+                return choice_map[response]
+
+            # Invalid input
+            print('Invalid choice. Please enter a number between 1 and 3.')
+
+        except KeyboardInterrupt:
+            if ask_yes_no('Confirm exit? (y/N) ', default=False):
+                print('\nService installation cancelled')
+                sys.exit(0)