zop-cli 0.2.0__tar.gz

zop_cli-0.2.0/.gitattributes

@@ -0,0 +1,15 @@
+# ─── Line endings ──────────────────────────────────────────────
+# Force LF on all text files, regardless of OS. Eliminates the
+# "LF will be replaced by CRLF" warnings on Windows checkouts
+# and keeps diffs clean in cross-platform teams.
+*.py   text eol=lf
+*.pyi  text eol=lf
+*.toml text eol=lf
+*.cfg  text eol=lf
+*.md   text eol=lf
+*.rst  text eol=lf
+*.json text eol=lf
+*.yml  text eol=lf
+*.yaml text eol=lf
+*.sh   text eol=lf
+*.txt  text eol=lf

zop_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v1
+
+  typecheck:
+    name: Mypy (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run mypy src
+
+  test:
+    name: pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run pytest --cov-report=xml
+      - if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

zop_cli-0.2.0/.gitignore

@@ -0,0 +1,50 @@
+# ─── Python build artifacts ────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+wheels/
+
+# ─── Virtual environments ──────────────────────────────────────
+.venv/
+venv/
+env/
+
+# ─── Test & coverage artifacts ─────────────────────────────────
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.pytest_cache/
+
+# ─── Linter & type-checker caches ──────────────────────────────
+.mypy_cache/
+.ruff_cache/
+
+# ─── Local agent/tool config ───────────────────────────────────
+# Plugin settings, skills, per-machine state — never commit
+.claude/
+.serena/
+CLAUDE.local.md
+
+# ─── Editor / IDE ──────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# ─── OS metadata ───────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ─── Logs ──────────────────────────────────────────────────────
+*.log
+logs/
+
+# ─── Local secrets & environment overrides ─────────────────────
+.env
+.env.*
+!.env.example

zop_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# 贡献与维护指南
+
+面向 zop 的贡献者与维护者。终端用户的安装/使用请看 [README](README.md);架构设计请看 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
+## 开发环境
+
+前置:**Python ≥ 3.12** 和 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+git clone https://github.com/kingdomad/zop.git
+cd zop
+uv sync                # 创建 .venv 并安装主依赖 + dev 依赖(ruff/mypy/pytest 等)
+uv run zop --version   # 验证可运行
+```
+
+## 项目结构
+
+四层(端口/适配器)架构,详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):
+
+```
+src/zop/
+├── core/        # 横切:config / errors / envelope / concurrency
+├── models/      # pydantic v2 数据模型 + 信封
+├── adapters/    # I/O 边界:sqlite_reader(读)/ zotero_api(写,async httpx)
+├── services/    # 业务编排(只调 adapter 公共方法)
+└── commands/    # 薄 click 包装(无业务逻辑)
+```
+
+**核心约束:service 层不得直接 import `httpx` / `sqlite3`** —— 只通过 adapter 的公共方法访问 I/O。这是可测试性和可替换性的基础。
+
+## 日常开发命令
+
+```bash
+uv run ruff check .        # lint(含 tools/、tests/)
+uv run ruff format         # 格式化
+uv run mypy src            # 严格类型检查(必须 0 错误)
+uv run pytest              # 全量测试 + 覆盖率报告
+uv run pytest tests/test_collections.py -v   # 单个文件
+uv run pytest -k plan      # 按名筛选
+```
+
+四者全绿才能提交。CI 跑的是同样的检查,本地绿 ≈ CI 绿(但 CI 在 Linux,注意跨平台)。
+
+## 测试约定
+
+- **栈**:pytest + pytest-asyncio(`asyncio_mode = "auto"`,async 测试无需逐个 mark)+ pytest-cov。
+- **fake_db**:`tests/conftest.py` 提供一个**空** sqlite 文件(SqliteReader 只检查路径存在);需要真实 schema 的测试在本地自建 —— 见 `tests/test_collections.py`(完整 10 表)和 `tests/test_cli_plan.py`(按需建表)。
+- **写入路径**:adapter 测试用 `httpx.MockTransport`(零依赖,不引 pytest-httpx);service 测试用 `AsyncMock(spec=ZoteroApi)` 注入。
+- **夹具**:自动化夹具放 `tests/fixtures/`(如 `test_plan.json`);一次性手工夹具别入库。
+- **覆盖率**:当前 ~64%,无 `--cov-fail-under` gate。优先覆盖关键写入路径和 CLI 命令,不为数字硬凑。
+
+## 代码风格
+
+- ruff:line-length 100,启用 E/W/F/I/B/UP/N/S/C4/RET/SIM/TID/PT/RUF;`tests/` 放宽 S101(assert)。
+- mypy:`strict = true`,对外部 `pypdf.*` 用 `ignore_missing_imports`。
+- 导入:禁止相对导入(`flake8-tidy-imports: ban-relative-imports = "all"`)。
+
+## 提交规范
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/):`feat` / `fix` / `test` / `refactor` / `chore` / `build` / `ci` / `docs`。一个逻辑单元一个原子提交。
+
+历史示例:`feat(skills): ...`、`test(plan): ...`、`build: rename distribution to zop-cli`。
+
+## CI
+
+`.github/workflows/ci.yml` 在 push/PR 到 `main` 时触发,三个并行作业:
+
+| 作业 | 内容 |
+|------|------|
+| Ruff | `ruff check`(全仓库) |
+| Mypy | `uv sync` + `mypy src`(strict) |
+| pytest | 矩阵 Python 3.12 / 3.13,`uv sync` + `pytest --cov-report=xml` |
+
+无覆盖率门槛 —— 测试全过即绿。
+
+## 版本管理
+
+单一来源:`src/zop/_version.py` 的 `__version__`(hatchling 读取,注入构建元数据)。发版流程:
+
+1. 改 `__version__`(如 `"0.3.0"`);
+2. 提交(`chore: bump version to 0.3.0`);
+3. 打 tag:`git tag v0.3.0 && git push --tags`;
+4. 按下一节发布到 PyPI。
+
+## 发布到 PyPI
+
+分发名是 **`zop-cli`**(命令仍是 `zop`,导入包仍是 `zop`)。
+
+**1. 配置 token**(一次性):在 PyPI 为 `zop-cli` 项目建一个 scoped API token,设为环境变量。uv **不读** `~/.pypirc`,用环境变量:
+
+```powershell
+# Windows(用户级,持久)
+[Environment]::SetEnvironmentVariable("UV_PUBLISH_TOKEN", "pypi-xxxxxxxx", "User")
+```
+
+```bash
+# macOS / Linux
+echo 'export UV_PUBLISH_TOKEN=pypi-xxxxxxxx' >> ~/.bashrc
+```
+
+**2. 构建 + 校验**:
+
+```bash
+uv build                       # 产出 dist/zop_cli-X.Y.Z-*.whl 和 .tar.gz
+uvx twine check dist/*         # 校验元数据(License-Expression、entry point 等)
+```
+
+**3. 发布**:
+
+```bash
+uv publish                     # 自动读取 UV_PUBLISH_TOKEN
+```
+
+**4. 验证**:换一个干净环境 `uv tool install zop-cli` 从 PyPI 装回来,确认 `zop --version` 和命令正常。
+
+**备选(自动化)**:在 GitHub Actions 用 [trusted publishing](https://docs.pypi.org/trusted-publishers/)(OIDC,免本地 token)—— 打 tag 触发 workflow 自动发布。适合稳定后接入。
+
+## 维护 agent skill
+
+仓库带一个面向 agent 的 skill(`skills/zop/`),用户通过 `npx skills add kingdomad/zop --skill zop` 安装。
+
+- **改 CLI 命令后,同步更新 `skills/zop/SKILL.md` 的命令表** —— agent 会照表调用,表里写错命令会导致 agent 调用失败。
+- skill 的 frontmatter `description` 只写"何时触发",不总结工作流(否则 agent 会只读 description 跳过正文)。
+- `skills/` 入库发布;`.claude/skills/` 是本地实验性 skill,**已 gitignore**,不会随仓库发布。
+
+## .gitignore 约定
+
+以下不入库(已在 `.gitignore`):`.claude/`、`.serena/`、`.venv/`、`.mypy_cache/`、`.pytest_cache/`、`.ruff_cache/`、`.coverage`、`*.sqlite`。新增临时/本地文件时遵循同样原则。

zop_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zop contributors
+
+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.

zop_cli-0.2.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: zop-cli
+Version: 0.2.0
+Summary: High-throughput Zotero CLI focused on batch operations and automation
+Project-URL: Homepage, https://github.com/anomalyco/zop
+Project-URL: Issues, https://github.com/anomalyco/zop/issues
+Author: zop contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: batch,bibliography,cli,zotero
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pypdf>=4.0
+Description-Content-Type: text/markdown
+
+# zop
+
+一个面向批量操作和自动化场景的高吞吐 Zotero 命令行工具。
+
+## 安装
+
+从 PyPI 安装(推荐):
+
+```bash
+uv tool install zop-cli
+```
+
+也可用 pipx:`pipx install zop-cli`,或 pip:`pip install zop-cli`。安装后命令名为 `zop`。
+
+开发安装(可编辑,含开发依赖):
+
+```bash
+uv sync
+```
+
+贡献与维护流程见 [CONTRIBUTING](CONTRIBUTING.md)。
+
+## 配置
+
+新建 `~/.config/zop/config.toml`:
+
+```toml
+[zotero]
+data_dir = "D:\\Program Data\\zotero"
+library_id = "12345"
+api_key = "your-api-key"
+```
+
+读取操作走本地 SQLite(`data_dir/zotero.sqlite`),写入操作走 Zotero Web API。
+读取无需联网,也不需要 API key。
+
+## 用法
+
+```bash
+zop collection list                    # 列出所有集合
+zop collection list --tree              # 以父子树形展示
+zop collection items ABC12345           # 列出某集合下的条目
+zop collection create "新主题"          # 创建集合
+zop collection create "子主题" --parent "新主题"
+zop collection delete ABC12345          # 删除集合(级联)
+zop collection reparent ABC12345 --parent "新父级"
+zop collection move KEY1 KEY2 --to TARGET_KEY   # 移动条目
+zop collection plan plan.json --dry-run        # 校验批量计划
+zop collection plan plan.json --execute       # 执行批量计划
+```
+
+## Agent skill
+
+为 AI 编程助手(Claude Code、Codex、Cursor 等)配套了一个 [agent skill](https://skills.sh),教 agent 如何调用 `zop`、解析 JSON 信封输出、以及批量 plan 的 dry-run → execute 流程:
+
+```bash
+npx skills add kingdomad/zop --skill zop -a claude-code -y
+```
+
+详见 [`skills/zop/SKILL.md`](skills/zop/SKILL.md)。
+
+## 与 `zot` 的差异
+
+- **真正的批量**:创建集合使用 Zotero 的批量 POST(每请求 50 条)
+- **有界并发 PATCH**:移动条目使用并行 PATCH(默认 8 路并发),而非逐条顺序调用
+- **真正的 dry-run**:`zop collection plan --dry-run` 会实际检查名称冲突、父级解析与条目存在性
+- **reparent 支持**:`zop collection reparent` 可用(`zot` 未暴露此能力)
+- **单条失败隔离**:批量移动中某一条失败不会中断整批任务

zop_cli-0.2.0/README.md

@@ -0,0 +1,68 @@
+# zop
+
+一个面向批量操作和自动化场景的高吞吐 Zotero 命令行工具。
+
+## 安装
+
+从 PyPI 安装(推荐):
+
+```bash
+uv tool install zop-cli
+```
+
+也可用 pipx:`pipx install zop-cli`,或 pip:`pip install zop-cli`。安装后命令名为 `zop`。
+
+开发安装(可编辑,含开发依赖):
+
+```bash
+uv sync
+```
+
+贡献与维护流程见 [CONTRIBUTING](CONTRIBUTING.md)。
+
+## 配置
+
+新建 `~/.config/zop/config.toml`:
+
+```toml
+[zotero]
+data_dir = "D:\\Program Data\\zotero"
+library_id = "12345"
+api_key = "your-api-key"
+```
+
+读取操作走本地 SQLite(`data_dir/zotero.sqlite`),写入操作走 Zotero Web API。
+读取无需联网,也不需要 API key。
+
+## 用法
+
+```bash
+zop collection list                    # 列出所有集合
+zop collection list --tree              # 以父子树形展示
+zop collection items ABC12345           # 列出某集合下的条目
+zop collection create "新主题"          # 创建集合
+zop collection create "子主题" --parent "新主题"
+zop collection delete ABC12345          # 删除集合(级联)
+zop collection reparent ABC12345 --parent "新父级"
+zop collection move KEY1 KEY2 --to TARGET_KEY   # 移动条目
+zop collection plan plan.json --dry-run        # 校验批量计划
+zop collection plan plan.json --execute       # 执行批量计划
+```
+
+## Agent skill
+
+为 AI 编程助手(Claude Code、Codex、Cursor 等)配套了一个 [agent skill](https://skills.sh),教 agent 如何调用 `zop`、解析 JSON 信封输出、以及批量 plan 的 dry-run → execute 流程:
+
+```bash
+npx skills add kingdomad/zop --skill zop -a claude-code -y
+```
+
+详见 [`skills/zop/SKILL.md`](skills/zop/SKILL.md)。
+
+## 与 `zot` 的差异
+
+- **真正的批量**:创建集合使用 Zotero 的批量 POST(每请求 50 条)
+- **有界并发 PATCH**:移动条目使用并行 PATCH(默认 8 路并发),而非逐条顺序调用
+- **真正的 dry-run**:`zop collection plan --dry-run` 会实际检查名称冲突、父级解析与条目存在性
+- **reparent 支持**:`zop collection reparent` 可用(`zot` 未暴露此能力)
+- **单条失败隔离**:批量移动中某一条失败不会中断整批任务