zop-cli 0.2.0__py3-none-any.whl

zop/core/envelope.py

@@ -0,0 +1,71 @@
+"""Output envelope helper."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from typing import Any
+
+from zop.core.errors import ZopError
+from zop.models.envelope import Envelope, Meta
+
+
+def emit(
+    data: Any = None,
+    *,
+    error: ZopError | None = None,
+    human: bool = False,
+    count: int | None = None,
+) -> None:
+    """Emit a JSON envelope to stdout.
+
+    Args:
+        data: Payload (will be JSON-serialized).
+        error: If provided, the envelope is marked as failed and `error` is
+            rendered as the error block.
+        human: If True, pretty-print; if False (default), compact JSON.
+        count: Optional item count for the meta block.
+    """
+    start = time.perf_counter_ns()
+    if error is not None:
+        env = Envelope(ok=False, error=error.to_block())
+    else:
+        env = Envelope(ok=True, data=data, meta=Meta(count=count))
+    latency_ms = int((time.perf_counter_ns() - start) / 1_000_000)
+    env = env.model_copy(update={"meta": env.meta.model_copy(update={"latency_ms": latency_ms})})
+
+    if human:
+        sys.stdout.write(env.to_human())
+    else:
+        sys.stdout.write(env.to_json())
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def emit_error(err: ZopError, *, human: bool = False) -> None:
+    """Emit a top-level error envelope."""
+    emit(error=err, human=human)
+
+
+def emit_batch(
+    successes: list[Any],
+    failures: list[tuple[str, ZopError]],
+    *,
+    human: bool = False,
+) -> None:
+    """Emit a batch result with both successes and per-item failures."""
+    data: dict[str, Any] = {
+        "succeeded": [s.model_dump() if hasattr(s, "model_dump") else s for s in successes],
+        "failed": [
+            {"key": k, "error": e.to_block().model_dump()}
+            for k, e in failures
+        ],
+    }
+    env = Envelope(ok=not failures, data=data, meta=Meta(count=len(successes) + len(failures)))
+    if human:
+        sys.stdout.write(json.dumps(env.model_dump(), indent=2, ensure_ascii=False))
+    else:
+        sys.stdout.write(env.to_json())
+    sys.stdout.write("\n")
+    sys.stdout.flush()

zop/core/errors.py

@@ -0,0 +1,92 @@
+"""Error types and structured Result."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TypeVar
+
+from zop.models.envelope import ErrorBlock
+
+T = TypeVar("T")
+
+
+class ZopError(Exception):
+    """Base error for all zop errors."""
+
+    code: str = "zop_error"
+    retryable: bool = False
+    hint: str | None = None
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        if hint is not None:
+            self.hint = hint
+
+    def to_block(self) -> ErrorBlock:
+        return ErrorBlock(
+            code=self.code,
+            message=self.message,
+            hint=self.hint,
+            retryable=self.retryable,
+        )
+
+
+class AuthError(ZopError):
+    code = "auth_missing"
+    hint = "Run 'zop config init' or set ZOP_LIBRARY_ID + ZOP_API_KEY env vars"
+
+
+class NotFoundError(ZopError):
+    code = "not_found"
+
+
+class ConflictError(ZopError):
+    """Resource already exists, or operation would create a conflict."""
+
+    code = "conflict"
+
+
+class ApiError(ZopError):
+    code = "api_error"
+    retryable = True
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+
+
+class ValidationError(ZopError):
+    code = "validation_error"
+
+
+class NetworkError(ZopError):
+    code = "network_error"
+    retryable = True
+
+
+@dataclass
+class BatchResult[T]:
+    """Result of a batch operation: successes + per-item failures."""
+
+    successes: list[T] = field(default_factory=list)
+    failures: list[tuple[str, ErrorBlock]] = field(default_factory=list)  # (key, error)
+
+    @property
+    def ok(self) -> bool:
+        return not self.failures
+
+    @property
+    def count(self) -> int:
+        return len(self.successes) + len(self.failures)
+
+    def add_failure(self, key: str, err: ZopError) -> None:
+        self.failures.append((key, err.to_block()))
+
+    def merge(self, other: BatchResult[T]) -> None:
+        self.successes.extend(other.successes)
+        self.failures.extend(other.failures)
+
+    def iter_failures(self) -> Iterable[tuple[str, ErrorBlock]]:
+        return iter(self.failures)

zop/models/__init__.py

@@ -0,0 +1,15 @@
+"""Data models (pydantic v2)."""
+
+from zop.models.collection import Collection, CollectionSummary, CollectionTree
+from zop.models.common import ID_PATTERN, ItemType
+from zop.models.item import Item, ItemSummary
+
+__all__ = [
+    "ID_PATTERN",
+    "Collection",
+    "CollectionSummary",
+    "CollectionTree",
+    "Item",
+    "ItemSummary",
+    "ItemType",
+]

zop/models/collection.py

@@ -0,0 +1,45 @@
+"""Collection models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from zop.models.common import ID_PATTERN
+
+
+class CollectionSummary(BaseModel):
+    """Minimal collection info (saves tokens for list views)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str = Field(pattern=ID_PATTERN)
+    name: str
+    parent_key: str | None = Field(default=None, pattern=ID_PATTERN)
+
+
+class Collection(CollectionSummary):
+    """Full collection info."""
+
+    version: int = 0
+    item_count: int = 0
+    synced: bool = True
+
+
+class CollectionTree(BaseModel):
+    """Collection as a node in a parent/child tree."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str = Field(pattern=ID_PATTERN)
+    name: str
+    parent_key: str | None = Field(default=None, pattern=ID_PATTERN)
+    item_count: int = 0
+    children: list[CollectionTree] = Field(default_factory=list)
+
+    def walk(self) -> Iterator[CollectionTree]:
+        """Pre-order traversal (self before descendants)."""
+        yield self
+        for child in self.children:
+            yield from child.walk()

zop/models/common.py

@@ -0,0 +1,30 @@
+"""Common model types."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+# Zotero item keys / collection keys are 8-char alphanumeric
+ID_PATTERN = r"^[A-Z0-9]{8}$"
+
+
+class ItemType(StrEnum):
+    """Subset of Zotero item types (extend as needed)."""
+
+    BOOK = "book"
+    BOOK_SECTION = "bookSection"
+    JOURNAL_ARTICLE = "journalArticle"
+    CONFERENCE_PAPER = "conferencePaper"
+    PREPRINT = "preprint"
+    REPORT = "report"
+    DOCUMENT = "document"
+    DATASET = "dataset"
+    WEBPAGE = "webpage"
+    COMPUTER_PROGRAM = "computerProgram"
+    THESIS = "thesis"
+    MANUSCRIPT = "manuscript"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def _missing_(cls, value: object) -> ItemType:
+        return cls.UNKNOWN

zop/models/envelope.py

@@ -0,0 +1,58 @@
+"""JSON envelope for all CLI output."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from zop import __version__
+
+
+class Meta(BaseModel):
+    """Response metadata."""
+
+    model_config = ConfigDict(frozen=True)
+
+    cli_version: str = __version__
+    request_id: str = Field(default_factory=lambda: uuid.uuid4().hex[:12])
+    latency_ms: int = 0
+    count: int | None = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class ErrorBlock(BaseModel):
+    """Error information block."""
+
+    model_config = ConfigDict(frozen=True)
+
+    code: str
+    message: str
+    hint: str | None = None
+    retryable: bool = False
+
+
+class Envelope(BaseModel):
+    """Top-level response envelope.
+
+    All CLI output (success or error) is wrapped in this structure so that
+    agents can rely on a stable shape.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    ok: bool
+    data: Any = None
+    error: ErrorBlock | None = None
+    meta: Meta = Field(default_factory=Meta)
+
+    def to_json(self) -> str:
+        """Serialize to JSON string (compact, deterministic)."""
+        return self.model_dump_json(exclude_none=True)
+
+    def to_human(self) -> str:
+        """Serialize to human-readable text (best-effort)."""
+        if not self.ok and self.error:
+            return f"Error [{self.error.code}]: {self.error.message}"
+        return self.model_dump_json(indent=2, exclude_none=True)

zop/models/item.py

@@ -0,0 +1,34 @@
+"""Item models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from zop.models.common import ID_PATTERN, ItemType
+
+
+class ItemSummary(BaseModel):
+    """Minimal item info (used for list views)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str = Field(pattern=ID_PATTERN)
+    item_type: ItemType
+    title: str
+    creators: list[str] = Field(default_factory=list)  # "Last, First" strings
+    year: int | None = None
+    date: str | None = None  # raw Zotero date string
+
+
+class Item(ItemSummary):
+    """Full item metadata."""
+
+    abstract: str | None = None
+    doi: str | None = None
+    url: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    collections: list[str] = Field(default_factory=list)  # keys
+    version: int = 0
+    date_added: str | None = None
+    date_modified: str | None = None
+    extra: dict[str, str] = Field(default_factory=dict)

zop/services/__init__.py

@@ -0,0 +1,19 @@
+"""Service layer: business orchestration."""
+
+from zop.services.collections import CollectionsService
+from zop.services.export import ExportService
+from zop.services.items import ItemsService
+from zop.services.library import LibraryService
+from zop.services.notes import NotesService
+from zop.services.pdf import PdfService
+from zop.services.tags import TagsService
+
+__all__ = [
+    "CollectionsService",
+    "ExportService",
+    "ItemsService",
+    "LibraryService",
+    "NotesService",
+    "PdfService",
+    "TagsService",
+]

zop/services/collections.py

@@ -0,0 +1,326 @@
+"""Collection service: business logic for collection operations.
+
+This layer:
+- Validates inputs
+- Resolves collection names <-> keys
+- Coordinates SQLite reads and Web API writes
+- Aggregates per-item failures in batch ops
+- Implements a real dry-run that checks existence + would-create conflicts
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.adapters.zotero_api import ApiCreds, ZoteroApi
+from zop.core.errors import (
+    AuthError,
+    NotFoundError,
+    ValidationError,
+    ZopError,
+)
+from zop.models.collection import Collection, CollectionTree
+
+
+@dataclass
+class PlanNode:
+    """One entry in a reorg plan.
+
+    `parent` is a NAME (resolved against current library state during validate).
+    `items` are item keys to assign to the new collection.
+    """
+
+    name: str
+    parent: str | None = None
+    items: list[str] = field(default_factory=list)
+    parent_key: str | None = None  # set during validate()
+
+
+@dataclass
+class PlanReport:
+    """Result of validating a plan against current library state."""
+
+    to_create: list[PlanNode] = field(default_factory=list)
+    item_assignments: list[tuple[str, str]] = field(default_factory=list)  # (item_key, coll_name)
+    conflicts: list[str] = field(default_factory=list)
+    unresolved_parents: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.conflicts and not self.unresolved_parents
+
+
+class CollectionsService:
+    """High-level collection operations."""
+
+    def __init__(
+        self,
+        db_path: Path | str | None = None,
+        *,
+        creds: ApiCreds | None = None,
+    ) -> None:
+        if db_path is None:
+            raise ValidationError(
+                "db_path required (set data_dir in config or pass explicitly)"
+            )
+        self._db_path = Path(db_path)
+        self._creds = creds
+        self._reader = SqliteReader(self._db_path)
+
+    # ---- Read ----
+
+    def list_all(self) -> list[Collection]:
+        return self._reader.list_collections()
+
+    def list_tree(self) -> list[CollectionTree]:
+        return self._reader.build_tree()
+
+    def get(self, key: str) -> Collection:
+        return self._reader.get_collection(key)
+
+    def items(self, key: str) -> list[str]:
+        return [it.key for it in self._reader.list_collection_items(key)]
+
+    def resolve(self, name: str) -> Collection:
+        for c in self.list_all():
+            if c.name == name:
+                return c
+        raise NotFoundError(f"No collection named '{name}'")
+
+    # ---- Plan validation (real dry-run) ----
+
+    def validate_plan(self, plan: list[PlanNode]) -> PlanReport:
+        """Check a plan against current state.
+
+        Validates:
+        - No duplicate names (vs current library)
+        - All parent references resolve to existing collections OR to other
+          nodes in the plan (which will be created first; creation is
+          topologically ordered so parents are created before children)
+        - All item keys exist locally (best-effort; the API will catch missed ones)
+        """
+        existing = {c.name: c for c in self.list_all()}
+        report = PlanReport()
+        plan_by_name: dict[str, PlanNode] = {n.name: n for n in plan}
+
+        # First pass: name uniqueness + item existence
+        for node in plan:
+            if not node.name.strip():
+                report.conflicts.append("Empty collection name in plan")
+                continue
+            if node.name in existing:
+                report.conflicts.append(
+                    f"Collection '{node.name}' already exists (key={existing[node.name].key})"
+                )
+                continue
+            # Defer to second pass for parent resolution
+
+        # Second pass: parent resolution + item checks (only on nodes that
+        # passed the uniqueness check)
+        for node in plan:
+            if any(node.name in c for c in report.conflicts if "already exists" in c):
+                continue  # skip nodes that failed uniqueness
+            if not node.name.strip():
+                continue
+            if node.parent:
+                if node.parent in existing:
+                    node.parent_key = existing[node.parent].key
+                elif node.parent in plan_by_name:
+                    # Parent will be created in the same plan; mark deferred.
+                    node.parent_key = "__PLAN_PARENT__"  # resolved at exec time
+                else:
+                    if node.parent not in report.unresolved_parents:
+                        report.unresolved_parents.append(node.parent)
+                    continue
+            report.to_create.append(node)
+
+            for item_key in node.items:
+                if not self._item_exists_locally(item_key):
+                    report.conflicts.append(
+                        f"Item '{item_key}' (for collection '{node.name}') not found locally"
+                    )
+                else:
+                    report.item_assignments.append((item_key, node.name))
+
+        return report
+
+    def _item_exists_locally(self, key: str) -> bool:
+        try:
+            with self._reader._connect() as con:
+                row = con.execute(
+                    "SELECT 1 FROM items WHERE key = ? LIMIT 1", (key,)
+                ).fetchone()
+            return row is not None
+        except Exception:
+            return False
+
+    # ---- Write (requires API credentials) ----
+
+    def _require_api(self) -> ZoteroApi:
+        if not self._creds or not self._creds.api_key:
+            raise AuthError("API credentials required for write operations")
+        return ZoteroApi(self._creds)
+
+    async def create(
+        self,
+        name: str,
+        *,
+        parent: str | None = None,
+    ) -> Collection:
+        """Create one collection. `parent` is the parent NAME."""
+        api = self._require_api()
+        payload: dict[str, object] = {"name": name}
+        if parent:
+            p = self.resolve(parent)
+            payload["parentCollection"] = p.key
+        async with api:
+            result = await api.create_collections([payload])
+        if not result:
+            raise ZopError(f"Failed to create '{name}' (empty response)")
+        r = result[0]
+        return Collection(
+            key=r["key"],
+            name=r["data"]["name"],
+            parent_key=r["data"].get("parentCollection") or None,
+            version=r["version"],
+        )
+
+    async def create_many(self, plan: list[PlanNode]) -> list[Collection]:
+        """Create all collections in a validated plan (batched POST, topologically ordered).
+
+        Handles intra-plan parent references: a node whose parent is another
+        node in the plan is created after its parent. We process in waves
+        (Kahn-style topological order), POSTing each wave as a batch.
+        """
+        report = self.validate_plan(plan)
+        if not report.ok:
+            raise ValidationError(
+                f"Plan invalid. conflicts={report.conflicts} unresolved={report.unresolved_parents}"
+            )
+
+        plan_by_name = {n.name: n for n in report.to_create}
+        # Build dependency: who depends on whom
+        # remaining[node] = set of node-names this node still waits on
+        remaining: dict[str, set[str]] = {}
+        for n in report.to_create:
+            if n.parent_key == "__PLAN_PARENT__" and n.parent in plan_by_name:
+                remaining[n.name] = {n.parent}
+            else:
+                remaining[n.name] = set()
+
+        api = self._require_api()
+        created: dict[str, Collection] = {}  # name -> Collection
+        async with api:
+            while remaining:
+                # Find nodes with no remaining dependencies
+                ready = [n for n in report.to_create if n.name in remaining and not remaining[n.name]]
+                if not ready:
+                    raise ValidationError("Plan has a cycle in parent references")
+                payloads: list[dict[str, object]] = []
+                for n in ready:
+                    parent_key: str | None = None
+                    if n.parent:
+                        if n.parent in created:
+                            parent_key = created[n.parent].key
+                        elif n.parent in plan_by_name and n.parent_key == "__PLAN_PARENT__":
+                            # Should have been picked up already by topo sort
+                            raise ValidationError(
+                                f"Parent '{n.parent}' not yet created for '{n.name}'"
+                            )
+                        else:
+                            # Use the resolved key from validate_plan (existing parent)
+                            parent_key = n.parent_key
+                    payloads.append(
+                        {"name": n.name, "parentCollection": parent_key}
+                    )
+                results = await api.create_collections(payloads)
+                if len(results) != len(ready):
+                    raise ZopError(
+                        f"API returned {len(results)} collections, expected {len(ready)}"
+                    )
+                for n, r in zip(ready, results, strict=True):
+                    c = Collection(
+                        key=r["key"],
+                        name=r["data"]["name"],
+                        parent_key=r["data"].get("parentCollection") or None,
+                        version=r["version"],
+                    )
+                    created[n.name] = c
+                # Remove processed nodes from remaining, decrement dependents
+                for n in ready:
+                    del remaining[n.name]
+                for deps in remaining.values():
+                    deps.difference_update({n.name for n in ready})
+
+        return list(created.values())
+
+    async def delete(self, key: str) -> None:
+        api = self._require_api()
+        async with api:
+            await api.delete_collection(key)
+
+    async def reparent(
+        self, key: str, new_parent: str | None, *, version: int | None = None
+    ) -> Collection:
+        """Move collection under new parent (NAME), or detach if new_parent is None."""
+
+        api = self._require_api()
+        if new_parent is None:
+            parent_key: str | None | object = False  # detach
+        else:
+            parent_key = self.resolve(new_parent).key
+        async with api:
+            r = await api.update_collection(key, parent_key=parent_key, version=version)
+        return Collection(
+            key=r["key"],
+            name=r["data"]["name"],
+            parent_key=r["data"].get("parentCollection") or None,
+            version=r["version"],
+        )
+
+    async def move_items(
+        self,
+        item_keys: Sequence[str],
+        to_collection_key: str,
+    ) -> tuple[list[str], list[tuple[str, Exception]]]:
+        """Add items to a collection (preserves existing memberships).
+
+        Fetches each item's current collections, adds the target, then
+        bounded-concurrent PATCH. Per-item failures are isolated.
+        """
+        api = self._require_api()
+        async with api:
+            # Fetch current state + version per item.
+            async def _fetch(k: str) -> tuple[str, list[str], int] | tuple[str, Exception]:
+                try:
+                    item = await api.get_item(k)
+                    colls = list(item["data"].get("collections", []))
+                    if to_collection_key not in colls:
+                        colls = [*colls, to_collection_key]
+                    return (k, colls, item["version"])
+                except Exception as e:
+                    return (k, e)
+
+            fetched = await asyncio.gather(
+                *[_fetch(k) for k in item_keys], return_exceptions=False
+            )
+
+            updates: list[tuple[str, list[str], int | None]] = []
+            fetch_failures: list[tuple[str, Exception]] = []
+            for r in fetched:
+                if len(r) == 3 and isinstance(r[1], list):
+                    _, colls, ver = r
+                    updates.append((r[0], colls, ver))
+                else:
+                    fetch_failures.append((r[0], r[1]))
+
+            ok, move_failures = await api.batch_update_item_collections(updates)
+
+        return ok, fetch_failures + move_failures
+
+
+__all__ = ["CollectionsService", "PlanNode", "PlanReport"]