paykka-kit 26.7.16__tar.gz

paykka_kit-26.7.16/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml

paykka_kit-26.7.16/.mise.toml

@@ -0,0 +1,38 @@
+[tools]
+python = "3.13"
+uv = "latest"
+ruff = "latest"
+
+[env]
+PYTHONUNBUFFERED = "1"
+
+[tasks.check]
+description = "Run linter, formatter check, and type checker"
+run = """
+  uv run ruff check . &&
+  uv run ruff format --check .
+"""
+
+[tasks.fmt]
+description = "Auto-format code"
+run = "uv run ruff format . && uv run ruff check --fix ."
+
+[tasks.test]
+description = "Run unit tests with pytest and coverage"
+run = "uv run pytest --cov=paykka_kit --cov-report=term-missing"
+
+[tasks.build]
+description = "Build distribution packages"
+run = "uv build"
+
+[tasks.publish]
+description = "Build and publish to PyPI"
+run = """
+  python scripts/bump-version.py &&
+  uv build &&
+  uv publish
+"""
+
+[tasks.cli]
+description = "Run paykka-kit CLI"
+run = "uv run pk $@"

paykka_kit-26.7.16/.python-version

@@ -0,0 +1 @@
+3.13

paykka_kit-26.7.16/AGENTS.md

@@ -0,0 +1,113 @@
+# AGENTS.md — paykka-kit AI 工作约束
+
+## 项目定位
+
+paykka-kit 是一个统一 CLI 工具集，将多个独立 CLI 工具整合到 `pk` 命令下。
+分发名 `paykka-kit`，包名 `paykka_kit`。
+
+## 技术栈
+
+- Python 3.13、Typer（CLI 框架）、Rich（终端输出）
+- 包管理 uv、工具链 mise、代码风格 ruff
+- 测试 pytest、类型检查 pyrefly（https://pyrefly.org/）
+
+## 开发铁律
+
+1. **TDD 先行**：任何功能必须先写失败的测试，再写实现，最后重构。
+
+   正确流程：
+   - RED：写测试 → `mise test` 红
+   - GREEN：最小实现 → `mise test` 绿
+   - REFACTOR：重构代码 → `mise test` 仍绿
+
+2. **提交前 `mise check`**：lint + format check + typecheck 必须全部通过。
+
+3. **配置隔离**：paykka-kit 全局配置只管理自身行为，不涉足模块业务配置。
+   每个模块的配置以 `<module_name>.json` 独立管理，模块自行读写校验。
+   详见「配置文件路径」章节。
+
+4. **异常体系**：所有异常继承 `PKError`（`core/exceptions.py`），使用退出码区分场景。
+   核心包所有公开类/函数以 `PK` 前缀命名（如 `PKError`、`PKTool`、`PKConfig`）。
+
+5. **统一输出**：所有终端输出通过 `core/console.py` 的 Console 实例，禁止直接 `print()`。
+
+6. **抽象优先**：新工具必须继承 `PKTool` 基类，实现 `name`/`help`/`register()`。
+
+## 全局 Flags
+
+| Flag | 短形式 | 作用 |
+|---|---|---|
+| `--verbose` | `-v` | 输出详细调试信息 |
+| `--output` | `-o` | 输出格式，支持 `json` / `table` |
+| `--version` | `-V` | 输出版本号并退出 |
+
+## 动态版本号
+
+格式: `YY.M.D[.commit_short]`
+
+- 基于构建当天日期，如 2026-07-16 → `26.7.16`
+- 当日多次构建则追加 7 位 commit SHA：`26.7.16.a1b2c3d`
+- 生成脚本：`scripts/bump-version.py`
+
+## 命令速查
+
+| 命令 | 作用 |
+|---|---|
+| `mise check` | lint + format-check + typecheck |
+| `mise fmt` | 自动格式化 |
+| `mise test` | 跑单测 + 覆盖率 |
+| `mise build` | 构建 wheel/sdist |
+| `mise publish` | 发布到 PyPI |
+| `mise cli` | 运行 CLI |
+
+## 配置文件路径
+
+遵循各平台约定，配置目录下以 `pk.json` 为全局配置、`<module_name>.json` 为模块专属配置。
+
+| 平台 | 路径 |
+|---|---|
+| Unix（Linux / macOS） | `$XDG_CONFIG_HOME/pk/pk.json`，默认 `~/.config/pk/pk.json` |
+| Windows | `%APPDATA%/pk/pk.json` |
+
+## 项目结构约定
+
+```
+paykka-kit/
+├── pyproject.toml
+├── .mise.toml
+├── .python-version              # 3.13
+├── ruff.toml
+├── AGENTS.md                    # 本文档
+├── CLAUDE.md -> AGENTS.md       # 软链接
+├── scripts/
+│   └── bump-version.py          # 动态版本生成脚本
+├── paykka_kit/                   # 源码根目录
+│   ├── main.py                  # Typer 入口，全局 flags
+│   ├── core/                    # 核心抽象层
+│   │   ├── version.py           # get_version()
+│   │   ├── config.py            # PKConfig (JSON)
+│   │   ├── console.py           # Rich Console 统一输出
+│   │   └── exceptions.py        # PKError 异常体系
+│   ├── tools/                   # 工具模块
+│   │   ├── base.py              # PKTool ABC
+│   │   └── <tool_name>/         # 每个工具独立子包
+│   │       ├── cli.py           # Typer 子命令组
+│   │       ├── client.py        # API 客户端
+│   │       └── models.py        # Pydantic 模型
+│   └── utils/                   # 共享工具函数
+│       ├── http.py              # httpx 封装
+│       └── display.py           # render_output (json/table)
+└── tests/                       # 测试，结构与源码一一对应
+    ├── conftest.py
+    ├── test_core/
+    └── test_tools/
+```
+
+## 编码风格
+
+- 所有模块使用 `from __future__ import annotations`
+- 类型注解覆盖率要求 100%
+- 公开 API 必须有 docstring（Google 风格）
+- 文件头不加 shebang（入口点由 pyproject.toml 的 scripts 声明）
+- ruff 规则以 `ruff.toml` 为准，不在本文档重复
+- 代码注释和 Git commit message 使用英文

paykka_kit-26.7.16/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

paykka_kit-26.7.16/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: paykka-kit
+Version: 26.7.16
+Summary: 统一 CLI 工具集
+Requires-Python: >=3.13
+Requires-Dist: rich>=14.0
+Requires-Dist: typer>=0.21.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=7.0; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paykka-kit
+
+统一 CLI 工具集。

paykka_kit-26.7.16/README.md

@@ -0,0 +1,3 @@
+# paykka-kit
+
+统一 CLI 工具集。

paykka_kit-26.7.16/paykka_kit/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/paykka_kit/_version.py

@@ -0,0 +1 @@
+__version__ = "26.7.16"

paykka_kit-26.7.16/paykka_kit/core/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/paykka_kit/core/config.py

@@ -0,0 +1,52 @@
+"""PKConfig — global config management following XDG / Windows APPDATA conventions."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+class PKConfig:
+    """paykka-kit global behaviour config; does NOT manage per-module settings.
+
+    Unix: $XDG_CONFIG_HOME/pk/pk.json (default ~/.config/pk/pk.json)
+    Windows: %APPDATA%/pk/pk.json
+    """
+
+    IS_WIN = sys.platform == "win32"
+
+    if IS_WIN:
+        CONFIG_DIR = Path(os.environ.get("APPDATA", "~/AppData/Roaming")) / "pk"
+    else:
+        CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "pk"
+
+    CONFIG_FILE = CONFIG_DIR / "pk.json"
+
+    def __init__(self) -> None:
+        self.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        self._data: dict = {}
+        if self.CONFIG_FILE.exists():
+            self._data = json.loads(self.CONFIG_FILE.read_text())
+
+    @property
+    def verbose(self) -> bool:
+        return self._data.get("verbose", False)
+
+    @property
+    def profile(self) -> str:
+        return self._data.get("profile", "default")
+
+    @property
+    def output(self) -> str:
+        return self._data.get("output", "table")
+
+    def set(self, key: str, value: object) -> None:
+        self._data[key] = value
+        self.CONFIG_FILE.write_text(json.dumps(self._data, indent=2, ensure_ascii=False))
+
+
+def get_module_config_path(module_name: str) -> Path:
+    """Return per-module config path: <CONFIG_DIR>/<module_name>.json."""
+    return PKConfig.CONFIG_DIR / f"{module_name}.json"

paykka_kit-26.7.16/paykka_kit/core/console.py

@@ -0,0 +1,20 @@
+"""Unified terminal output via Rich Console with PK_THEME."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.theme import Theme
+
+PK_THEME = Theme(
+    {
+        "info": "cyan",
+        "success": "green",
+        "warning": "yellow",
+        "error": "red bold",
+        "title": "bold magenta",
+        "key": "bold blue",
+    }
+)
+
+std_console = Console(theme=PK_THEME)
+error_console = Console(stderr=True, theme=PK_THEME)

paykka_kit-26.7.16/paykka_kit/core/exceptions.py

@@ -0,0 +1,21 @@
+"""PKError — base exception class for paykka-kit, all errors derive from here."""
+
+from __future__ import annotations
+
+import typer
+
+
+class PKError(typer.Exit):
+    """Base class for all paykka-kit exceptions.
+
+    Args:
+        message: Human-readable error description.
+        code: Exit code, defaults to 1.
+    """
+
+    def __init__(self, message: str = "", *, code: int = 1) -> None:
+        super().__init__(code=code)
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message

paykka_kit-26.7.16/paykka_kit/core/version.py

@@ -0,0 +1,13 @@
+"""Version lookup — reads from installed package metadata."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def get_version() -> str:
+    """Return the installed paykka-kit version string."""
+    try:
+        return version("paykka-kit")
+    except PackageNotFoundError:
+        return "dev"

paykka_kit-26.7.16/paykka_kit/main.py

@@ -0,0 +1,57 @@
+"""paykka-kit CLI entry point — 'pk' command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from paykka_kit.core.console import std_console
+from paykka_kit.core.version import get_version
+
+app = typer.Typer(
+    name="pk",
+    help="Unified CLI toolkit",
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(*, value: bool) -> None:
+    """Callback for --version / -V: print version and exit."""
+    if value:
+        std_console.print(f"pk [bold]{get_version()}[/bold]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Enable verbose debug output"),
+    ] = False,
+    output: Annotated[
+        str,
+        typer.Option("--output", "-o", help="Output format: json or table"),
+    ] = "table",
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Global options injected into context for all subcommands."""
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+    ctx.obj["output"] = output
+
+
+def cli() -> None:
+    """Programmatic entry point — used by pyproject.toml [project.scripts]."""
+    app()

paykka_kit-26.7.16/paykka_kit/tools/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/paykka_kit/tools/base.py

@@ -0,0 +1,34 @@
+"""PKTool — abstract base class for all CLI tool modules."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import typer
+
+
+class PKTool(ABC):
+    """Abstract base for every CLI tool under paykka-kit.
+
+    Each subclass MUST define:
+      - name: the subcommand name (e.g. "opsany")
+      - help: a one-line description for the help text
+      - register(): return a configured typer.Typer instance
+    """
+
+    name: str = ""
+    help: str = ""
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if cls.__name__ == "PKTool" or cls.__module__.endswith(".base"):
+            return  # Allow the base class itself to be defined
+        if not cls.name:
+            raise TypeError(f"{cls.__name__} must define a 'name' class attribute")
+        if not cls.help:
+            raise TypeError(f"{cls.__name__} must define a 'help' class attribute")
+
+    @abstractmethod
+    def register(self) -> typer.Typer:
+        """Return a configured typer.Typer for this tool."""
+        ...

paykka_kit-26.7.16/paykka_kit/utils/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/paykka_kit/utils/display.py

@@ -0,0 +1,45 @@
+"""Unified output formatters — json / table."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+_PLACEHOLDER = "[dim]—[/dim]"
+
+
+def _cell(v: Any) -> str:
+    """Format a table cell value, using dim placeholder for None / empty string."""
+    if v is None or v == "":
+        return _PLACEHOLDER
+    return str(v)
+
+
+def render_output(data: list[dict[str, Any]], fmt: str, console: Console) -> None:
+    """Render data in the specified format.
+
+    Args:
+        data: List of dicts to render.
+        fmt: Output format, either "json" or "table".
+        console: Rich Console instance.
+
+    Raises:
+        ValueError: If the format is unsupported.
+    """
+    if fmt == "json":
+        console.print(json.dumps(data, indent=2, ensure_ascii=False))
+    elif fmt == "table":
+        if not data:
+            console.print("[dim](no data)[/dim]")
+            return
+        table = Table(show_edge=False, show_lines=False)
+        for key in data[0]:
+            table.add_column(key)
+        for row in data:
+            table.add_row(*[_cell(v) for v in row.values()])
+        console.print(table)
+    else:
+        raise ValueError(f"Unsupported output format: {fmt}")

paykka_kit-26.7.16/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "paykka-kit"
+dynamic = ["version"]
+description = "统一 CLI 工具集"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "typer>=0.21.0",
+    "rich>=14.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov>=7.0",
+    "ruff>=0.12.0",
+]
+
+[project.scripts]
+paykka-kit = "paykka_kit.main:cli"
+pk = "paykka_kit.main:cli"
+
+[tool.hatch.version]
+path = "paykka_kit/_version.py"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

paykka_kit-26.7.16/ruff.toml

@@ -0,0 +1,9 @@
+line-length = 100
+
+[lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

paykka_kit-26.7.16/scripts/bump-version.py

@@ -0,0 +1,55 @@
+"""Dynamic version generator: YY.M.D[.commit_short]"""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import date
+from pathlib import Path
+
+
+def get_version() -> str:
+    """Generate version string based on today's date and optional commit SHA."""
+    today = date.today()
+    base = f"{today.year % 100}.{today.month}.{today.day}"
+
+    try:
+        sha = (
+            subprocess.check_output(
+                ["git", "rev-parse", "--short=7", "HEAD"],
+                stderr=subprocess.DEVNULL,
+            )
+            .decode()
+            .strip()
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        sha = ""
+
+    # Check if HEAD already has a tag (first release of the day)
+    try:
+        existing_tags = (
+            subprocess.check_output(
+                ["git", "tag", "--points-at", "HEAD"],
+                stderr=subprocess.DEVNULL,
+            )
+            .decode()
+            .strip()
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        existing_tags = ""
+
+    if existing_tags or not sha:
+        return base
+    return f"{base}.{sha}"
+
+
+def main() -> None:
+    version = get_version()
+    # Write version to _version.py so hatchling can pick it up
+    version_file = Path("paykka_kit") / "_version.py"
+    version_file.parent.mkdir(parents=True, exist_ok=True)
+    version_file.write_text(f'__version__ = "{version}"\n')
+    print(f"Version: {version}")
+
+
+if __name__ == "__main__":
+    main()

paykka_kit-26.7.16/tests/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/tests/conftest.py

@@ -0,0 +1,12 @@
+"""共享 fixtures."""
+
+from __future__ import annotations
+
+import pytest
+from typer.testing import CliRunner
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    """Typer CLI 测试 runner."""
+    return CliRunner()

paykka_kit-26.7.16/tests/test_core/__init__.py

@@ -0,0 +1 @@
+""""""

paykka_kit-26.7.16/tests/test_core/test_config.py

@@ -0,0 +1,87 @@
+"""Tests for PKConfig."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from paykka_kit.core.config import PKConfig, get_module_config_path
+
+
+class TestPKConfig:
+    """PKConfig global config tests."""
+
+    def test_config_dir_is_xdg_based(self) -> None:
+        """On Unix, config directory follows XDG spec."""
+        config_dir = PKConfig.CONFIG_DIR
+        assert config_dir.name == "pk"
+        assert ".config" in str(config_dir)
+
+    def test_config_file_is_pk_json(self) -> None:
+        """Config file is named pk.json."""
+        config_file = PKConfig.CONFIG_FILE
+        assert config_file.name == "pk.json"
+
+    def test_default_values(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Returns defaults when no config file exists."""
+        monkeypatch.setattr(PKConfig, "CONFIG_FILE", tmp_path / "pk.json")
+        cfg = PKConfig()
+        assert cfg.verbose is False
+        assert cfg.profile == "default"
+        assert cfg.output == "table"
+
+    def test_load_from_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Loads values from an existing config file."""
+        config_file = tmp_path / "pk.json"
+        config_file.write_text(json.dumps({"verbose": True, "profile": "staging"}))
+        monkeypatch.setattr(PKConfig, "CONFIG_FILE", config_file)
+        cfg = PKConfig()
+        assert cfg.verbose is True
+        assert cfg.profile == "staging"
+
+    def test_set_saves_to_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """set() persists values to the config file."""
+        config_file = tmp_path / "pk.json"
+        monkeypatch.setattr(PKConfig, "CONFIG_FILE", config_file)
+        cfg = PKConfig()
+        cfg.set("verbose", True)
+        cfg.set("output", "json")
+        assert config_file.exists()
+        data = json.loads(config_file.read_text())
+        assert data["verbose"] is True
+        assert data["output"] == "json"
+
+    def test_empty_config_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Empty config file uses defaults."""
+        config_file = tmp_path / "pk.json"
+        config_file.write_text(json.dumps({}))
+        monkeypatch.setattr(PKConfig, "CONFIG_FILE", config_file)
+        cfg = PKConfig()
+        assert cfg.verbose is False
+
+
+class TestGetModuleConfigPath:
+    """get_module_config_path tests."""
+
+    def test_returns_config_dir_path(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Returns <CONFIG_DIR>/<module_name>.json."""
+        monkeypatch.setattr(PKConfig, "CONFIG_DIR", Path("/tmp/pk"))
+        path = get_module_config_path("opsany")
+        assert path == Path("/tmp/pk/opsany.json")
+
+
+class TestPKDir:
+    """Config directory creation tests."""
+
+    def test_config_dir_created_on_init(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Config directory is auto-created on first init."""
+        pk_dir = tmp_path / "pk"
+        monkeypatch.setattr(PKConfig, "CONFIG_DIR", pk_dir)
+        monkeypatch.setattr(PKConfig, "CONFIG_FILE", pk_dir / "pk.json")
+        PKConfig()
+        assert pk_dir.exists()
+        assert pk_dir.is_dir()