devkit-tools 0.1.0__py3-none-any.whl

dev_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""devkit — 面向开发者的命令行工具包。"""
+
+__version__ = "0.1.0"

dev_toolkit/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

dev_toolkit/cli.py

@@ -0,0 +1,19 @@
+"""devkit 主 CLI 组。"""
+
+from __future__ import annotations
+
+import click
+
+from . import __version__
+from .convert import convert_cmd
+from .envcheck import envcheck_cmd
+
+
+@click.group()
+@click.version_option(__version__, prog_name="devkit")
+def cli() -> None:
+    """devkit — 面向开发者的命令行工具包。"""
+
+
+cli.add_command(convert_cmd)
+cli.add_command(envcheck_cmd)

dev_toolkit/convert/__init__.py

@@ -0,0 +1,6 @@
+"""convert 模块：JSON / YAML / TOML / CSV 互转。"""
+
+from .cli import convert_cmd
+from .core import convert
+
+__all__ = ["convert", "convert_cmd"]

dev_toolkit/convert/cli.py

@@ -0,0 +1,55 @@
+"""convert 子命令的 Click 入口。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .core import convert
+from .handlers import FORMATS, ConvertError
+
+# JSON/YAML/TOML 整树加载，设输入大小上限（requirements.md NF-001）
+MAX_INPUT_BYTES = 50 * 1024 * 1024
+
+
+@click.command("convert")
+@click.argument("input", type=click.Path(dir_okay=False, path_type=Path), required=False)
+@click.argument("output", type=click.Path(dir_okay=False, path_type=Path), required=False)
+@click.option("--from", "from_fmt", type=click.Choice(FORMATS), help="输入格式（默认自动检测）")
+@click.option("--to", "to_fmt", type=click.Choice(FORMATS), help="输出格式（默认按 output 扩展名）")
+@click.option("--pretty", is_flag=True, help="美化输出")
+def convert_cmd(input: Path | None, output: Path | None,
+                from_fmt: str | None, to_fmt: str | None, pretty: bool) -> None:
+    """在 JSON / YAML / TOML / CSV 之间转换。
+
+    INPUT 省略时从 stdin 读取；OUTPUT 省略时写到 stdout。
+    """
+    filename = None
+    if input is None:
+        text = sys.stdin.read()
+    else:
+        raw = input.read_bytes()
+        if len(raw) > MAX_INPUT_BYTES:
+            raise click.ClickException(
+                f"输入超过上限 {MAX_INPUT_BYTES} 字节；大文件转换暂不支持"
+            )
+        text = raw.decode("utf-8")
+        filename = input.name
+
+    if to_fmt is None and output is not None:
+        from .core import detect_format
+        to_fmt = detect_format("", output.name)
+    if to_fmt is None:
+        raise click.ClickException("无法确定输出格式，请用 --to 指定")
+
+    try:
+        result = convert(text, to_fmt, from_fmt=from_fmt, filename=filename, pretty=pretty)
+    except ConvertError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if output is None:
+        click.echo(result, nl=False)
+    else:
+        output.write_text(result, encoding="utf-8")

dev_toolkit/convert/core.py

@@ -0,0 +1,40 @@
+"""convert 统一转换接口：格式检测 + 读 → 写。"""
+
+from __future__ import annotations
+
+from .handlers import FORMATS, ConvertError, dump, load
+
+_EXT = {
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".csv": "csv",
+}
+
+# ponytail: 内容嗅探只覆盖无歧义的首字符；拿不准就让用户用 --from。
+def detect_format(text: str, filename: str | None = None) -> str | None:
+    """从扩展名优先、内容嗅探兜底地推断格式。无法确定返回 None。"""
+    if filename:
+        for ext, fmt in _EXT.items():
+            if filename.lower().endswith(ext):
+                return fmt
+    stripped = text.lstrip()
+    if not stripped:
+        return None
+    if stripped[0] in "{[":
+        return "json"
+    return None
+
+
+def convert(text: str, to_fmt: str, from_fmt: str | None = None,
+            filename: str | None = None, pretty: bool = False) -> str:
+    if from_fmt is None:
+        from_fmt = detect_format(text, filename)
+    if from_fmt is None:
+        raise ConvertError(
+            "无法自动检测输入格式，请用 --from 指定"
+            f"（支持：{', '.join(FORMATS)}）"
+        )
+    data = load(text, from_fmt)
+    return dump(data, to_fmt, pretty=pretty)

dev_toolkit/convert/handlers.py

@@ -0,0 +1,125 @@
+"""各数据格式的读写处理器。
+
+读 → 统一的 Python dict/list/scalar 数据模型 → 写。
+CSV 仅支持二维表（表头 + 行记录），见 requirements.md 2.2.1 转换边界。
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import sys
+from typing import Any
+
+import yaml
+
+# TOML 读：tomllib(3.11+) / tomli(3.10 回退)；写：tomli-w
+if sys.version_info >= (3, 11):
+    import tomllib as _toml_read
+else:  # pragma: no cover - 仅 3.10 走这里
+    import tomli as _toml_read
+
+import tomli_w
+
+FORMATS = ("json", "yaml", "toml", "csv")
+
+
+class ConvertError(ValueError):
+    """转换边界相关的可预期错误（格式不支持、CSV 结构不符等）。"""
+
+
+# ---- 读：bytes/str → 数据模型 ----
+
+def _load_json(text: str) -> Any:
+    return json.loads(text)
+
+
+def _load_yaml(text: str) -> Any:
+    return yaml.safe_load(text)
+
+
+def _load_toml(text: str) -> Any:
+    return _toml_read.loads(text)
+
+
+def _load_csv(text: str) -> list[dict[str, str]]:
+    return list(csv.DictReader(io.StringIO(text)))
+
+
+_LOADERS = {
+    "json": _load_json,
+    "yaml": _load_yaml,
+    "toml": _load_toml,
+    "csv": _load_csv,
+}
+
+
+# ---- 写：数据模型 → str ----
+
+def _dump_json(data: Any, pretty: bool) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2 if pretty else None)
+
+
+def _dump_yaml(data: Any, pretty: bool) -> str:
+    # pretty 对 YAML 无额外含义；safe_dump 已是可读多行格式
+    return yaml.safe_dump(data, allow_unicode=True, sort_keys=False)
+
+
+def _dump_toml(data: Any, pretty: bool) -> str:
+    if not isinstance(data, dict):
+        raise ConvertError("TOML 顶层必须是表（dict），无法写入列表或标量")
+    return tomli_w.dumps(data)
+
+
+def _dump_csv(data: Any, pretty: bool) -> str:
+    rows = _as_table(data)
+    fieldnames: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in fieldnames:
+                fieldnames.append(key)
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=fieldnames)
+    writer.writeheader()
+    writer.writerows(rows)
+    return buf.getvalue()
+
+
+def _as_table(data: Any) -> list[dict[str, Any]]:
+    """把数据模型规约为 CSV 二维表（list[dict[扁平标量]]），否则显式失败。"""
+    if isinstance(data, dict):
+        data = [data]
+    if not isinstance(data, list):
+        raise ConvertError("CSV 仅支持二维表：需要对象列表或单个对象")
+    rows: list[dict[str, Any]] = []
+    for item in data:
+        if not isinstance(item, dict):
+            raise ConvertError("CSV 行必须是对象（dict）")
+        for key, value in item.items():
+            if isinstance(value, (dict, list)):
+                raise ConvertError(
+                    f"CSV 不支持嵌套字段 {key!r}；请先显式展开为扁平字段"
+                )
+        rows.append(item)
+    return rows
+
+
+_DUMPERS = {
+    "json": _dump_json,
+    "yaml": _dump_yaml,
+    "toml": _dump_toml,
+    "csv": _dump_csv,
+}
+
+
+def load(text: str, fmt: str) -> Any:
+    if fmt not in _LOADERS:
+        raise ConvertError(f"不支持的输入格式：{fmt}（支持：{', '.join(FORMATS)}）")
+    return _LOADERS[fmt](text)
+
+
+def dump(data: Any, fmt: str, pretty: bool = False) -> str:
+    if fmt not in _DUMPERS:
+        raise ConvertError(f"不支持的输出格式：{fmt}（支持：{', '.join(FORMATS)}）")
+    return _DUMPERS[fmt](data, pretty)

dev_toolkit/envcheck/__init__.py

@@ -0,0 +1,5 @@
+"""envcheck 模块：开发环境只读诊断。"""
+
+from .cli import envcheck_cmd
+
+__all__ = ["envcheck_cmd"]

dev_toolkit/envcheck/checks.py

@@ -0,0 +1,73 @@
+"""单个工具检查的实现：定位可执行文件、取版本、比对最低版本。"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+from packaging.version import InvalidVersion, Version
+
+_VERSION_RE = re.compile(r"(\d+\.\d+(?:\.\d+)?)")
+
+
+@dataclass
+class CheckSpec:
+    """一条检查规格（来自 YAML 配置）。"""
+
+    name: str
+    command: str
+    version_arg: str = "--version"
+    min_version: str | None = None
+
+
+@dataclass
+class CheckResult:
+    name: str
+    found: bool
+    path: str | None
+    version: str | None
+    ok: bool
+    detail: str
+
+    def suggestion(self) -> str | None:
+        if not self.found:
+            return f"未找到 {self.name}，请安装并确保其在 PATH 中"
+        if not self.ok:
+            return f"{self.name} 版本 {self.version} 低于要求，请升级"
+        return None
+
+
+def _query_version(command: str, version_arg: str) -> str | None:
+    try:
+        proc = subprocess.run(
+            [command, version_arg],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    output = (proc.stdout or "") + (proc.stderr or "")
+    match = _VERSION_RE.search(output)
+    return match.group(1) if match else None
+
+
+def run_check(spec: CheckSpec) -> CheckResult:
+    path = shutil.which(spec.command)
+    if path is None:
+        return CheckResult(spec.name, False, None, None, False, "未安装或不在 PATH")
+
+    version = _query_version(spec.command, spec.version_arg)
+    if spec.min_version is None:
+        return CheckResult(spec.name, True, path, version, True, "已安装")
+
+    if version is None:
+        return CheckResult(spec.name, True, path, None, False, "无法解析版本")
+
+    try:
+        ok = Version(version) >= Version(spec.min_version)
+    except InvalidVersion:
+        return CheckResult(spec.name, True, path, version, False, "版本号格式异常")
+
+    detail = "满足要求" if ok else f"需要 >= {spec.min_version}"
+    return CheckResult(spec.name, True, path, version, ok, detail)

dev_toolkit/envcheck/cli.py

@@ -0,0 +1,27 @@
+"""envcheck 子命令的 Click 入口。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .core import load_specs, run_all
+from .reporters import render
+
+
+@click.command("envcheck")
+@click.option("--config", type=click.Path(exists=True, dir_okay=False, path_type=Path),
+              help="YAML 检查项配置（默认使用预置检查项）")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table",
+              show_default=True, help="报告格式（html 属 v0.2+）")
+@click.option("--suggest-fix", is_flag=True, help="输出修复建议（不修改系统）")
+def envcheck_cmd(config: Path | None, fmt: str, suggest_fix: bool) -> None:
+    """诊断开发环境：检查必备工具的安装与版本。"""
+    specs = load_specs(config)
+    results = run_all(specs)
+    click.echo(render(results, fmt, suggest_fix))
+    # 任一检查未通过 → 非零退出码（requirements.md NF-003）
+    if any(not r.ok for r in results):
+        sys.exit(1)

dev_toolkit/envcheck/core.py

@@ -0,0 +1,41 @@
+"""envcheck 引擎：加载配置 → 并行跑检查 → 汇总结果。"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+import yaml
+
+from .checks import CheckResult, CheckSpec, run_check
+
+# 无配置文件时的预置检查项
+DEFAULT_CHECKS = [
+    CheckSpec("Python", "python", "--version", "3.10"),
+    CheckSpec("Git", "git", "--version"),
+    CheckSpec("Node.js", "node", "--version"),
+    CheckSpec("Docker", "docker", "--version"),
+    CheckSpec("Go", "go", "version"),
+    CheckSpec("Rust", "rustc", "--version"),
+]
+
+
+def load_specs(config: Path | None) -> list[CheckSpec]:
+    if config is None:
+        return DEFAULT_CHECKS
+    data = yaml.safe_load(config.read_text(encoding="utf-8")) or {}
+    specs = []
+    for item in data.get("checks", []):
+        specs.append(CheckSpec(
+            name=item["name"],
+            command=item["command"],
+            version_arg=item.get("version_arg", "--version"),
+            min_version=item.get("min_version"),
+        ))
+    return specs
+
+
+def run_all(specs: list[CheckSpec]) -> list[CheckResult]:
+    # 检查项可并行执行（requirements.md 2.4 #5）；I/O 密集用线程足够
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        return list(pool.map(run_check, specs))

dev_toolkit/envcheck/reporters.py

@@ -0,0 +1,49 @@
+"""envcheck 报告输出：table / json。
+
+HTML 报告属 v0.2+ 路线图（requirements.md 2.6 Later），v0.1 不实现。
+"""
+
+from __future__ import annotations
+
+import json
+
+from .checks import CheckResult
+
+
+def report_table(results: list[CheckResult], suggest_fix: bool) -> str:
+    lines = []
+    width = max((len(r.name) for r in results), default=4)
+    for r in results:
+        mark = "OK " if r.ok else "FAIL"
+        ver = r.version or "-"
+        lines.append(f"[{mark}] {r.name:<{width}}  {ver:<12}  {r.detail}")
+    if suggest_fix:
+        fixes = [s for r in results if (s := r.suggestion())]
+        if fixes:
+            lines.append("")
+            lines.append("修复建议：")
+            lines.extend(f"  - {f}" for f in fixes)
+    return "\n".join(lines)
+
+
+def report_json(results: list[CheckResult], suggest_fix: bool) -> str:
+    payload = []
+    for r in results:
+        entry = {
+            "name": r.name,
+            "found": r.found,
+            "path": r.path,
+            "version": r.version,
+            "ok": r.ok,
+            "detail": r.detail,
+        }
+        if suggest_fix:
+            entry["suggestion"] = r.suggestion()
+        payload.append(entry)
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def render(results: list[CheckResult], fmt: str, suggest_fix: bool) -> str:
+    if fmt == "json":
+        return report_json(results, suggest_fix)
+    return report_table(results, suggest_fix)

devkit_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: devkit-tools
+Version: 0.1.0
+Summary: 面向开发者的命令行工具包：数据格式转换 + 环境诊断
+Project-URL: Homepage, https://github.com/yukinpost/devkit-cli
+Project-URL: Issues, https://github.com/yukinpost/devkit-cli/issues
+Author-email: yukinpost <jasonliaojx98@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,convert,envcheck,json,toml,yaml
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: packaging>=23.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# devkit-tools
+
+[![CI](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml)
+
+面向开发者的命令行工具包。v0.1 提供两个开箱即用的子命令：
+
+- **`convert`** — 在 JSON / YAML / TOML / CSV 之间互相转换
+- **`envcheck`** — 诊断开发环境中必备工具的安装与版本
+
+> 路线图模块（`templater` / `watch` / `gitstats`）见 [docs/requirements.md](docs/requirements.md)，将在 v0.2+ 实现。
+
+## 安装
+
+```bash
+pip install devkit-tools
+```
+
+需要 Python 3.10+。
+
+## convert
+
+```bash
+# 文件互转（输出格式由扩展名推断）
+devkit convert config.json config.yaml
+
+# 显式指定格式
+devkit convert data.txt --from json --to toml
+
+# 管道模式
+cat data.json | devkit convert --to yaml
+
+# 美化输出
+devkit convert data.json --to json --pretty
+```
+
+支持矩阵与边界（如 CSV 仅支持二维表）见 [docs/requirements.md](docs/requirements.md) 2.2.1。
+
+## envcheck
+
+```bash
+# 用预置检查项诊断环境
+devkit envcheck
+
+# 自定义检查项 + 输出修复建议
+devkit envcheck --config examples/config/dev-toolkit.yml --suggest-fix
+
+# JSON 报告（便于 CI 消费）
+devkit envcheck --format json
+```
+
+任一检查未通过时返回非零退出码。`--suggest-fix` 只输出建议，**不会修改你的系统**。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest          # 测试 + 覆盖率
+ruff check .    # lint
+mypy            # 类型检查
+```
+
+## License
+
+[MIT](LICENSE)

devkit_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+dev_toolkit/__init__.py,sha256=KGDCUdaySLJ91l-9PXsq40jJxBg6OCf3GdZdIWGEbgc,80
+dev_toolkit/__main__.py,sha256=8hDtWlaFZK24KhfNq_ZKgtXqYHsDQDetukOCMlsbW0Q,59
+dev_toolkit/cli.py,sha256=myujRTrg5as8eL4i6DNifRjQDZHVrRVKKCAeKofSVw8,386
+dev_toolkit/convert/__init__.py,sha256=Ji1m1-_F737VfIOW8Z2h5XAgJMOGUXPl_1bMcKzG3pA,152
+dev_toolkit/convert/cli.py,sha256=HppjOsQEGF2kxPeHJJ1UTHSu7zXixEHm6p9uQ2XwSco,2002
+dev_toolkit/convert/core.py,sha256=C3XQFdmeg-kwNl0abWq-1-JIyeWvggW6mEER3AY_CBU,1268
+dev_toolkit/convert/handlers.py,sha256=o0TK-7PQik5wWd1_Piuc4y7FkMXSE23_ApTuEand5U8,3445
+dev_toolkit/envcheck/__init__.py,sha256=mrhO5oQtI41nE6BDGpvi-i9yQsQT8fs35xo3zQSp-Uo,111
+dev_toolkit/envcheck/checks.py,sha256=zVEIpgaf25cuh2ibzmfuo_hm3frt5l6xxKMYQwICF0w,2137
+dev_toolkit/envcheck/cli.py,sha256=Rn7mwmodFjI0UMlM3d4Idfypz0v2HDtfa1LYaN5-HWw,1040
+dev_toolkit/envcheck/core.py,sha256=0N-p9EotwnarUpNFDjW3NKQ4nWB_e1zzHCuIWi0XBlY,1314
+dev_toolkit/envcheck/reporters.py,sha256=AHY-cGd_yNe3WsZdx9eKP_vhNpPsLBAWqPiP4x95PYE,1457
+devkit_tools-0.1.0.dist-info/METADATA,sha256=NhxPCD78d-gt6DxPL2DTKQQ_ICzumYmnXaYJk-9dzCM,2761
+devkit_tools-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+devkit_tools-0.1.0.dist-info/entry_points.txt,sha256=NMEr1Y1mN_WFDDEdPrUxhsByqtJOCHYVm6ZC7-NsVRg,47
+devkit_tools-0.1.0.dist-info/licenses/LICENSE,sha256=6vA3xWebNN8urkgFj8MH5DLC3mGwtMg8PPD1MRtw_kY,1067
+devkit_tools-0.1.0.dist-info/RECORD,,

devkit_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

devkit_tools-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devkit = dev_toolkit.cli:cli

devkit_tools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Liao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.