cite2site 1.0.0__py3-none-any.whl

c2s/__init__.py

@@ -0,0 +1,24 @@
+"""Cite2Site first-slice implementation."""
+
+__all__ = [
+    "__version__",
+    "BaseAdapter",
+    "FilesystemTextAdapter",
+    "MarkdownAdapter",
+    "AdapterArtifact",
+    "get_adapter",
+    "adapter_for_uri",
+    "adapter_diagnostics",
+]
+
+__version__ = "1.0.0"
+
+from .adapter import (  # noqa: E402  — re-export after version
+    AdapterArtifact,
+    BaseAdapter,
+    FilesystemTextAdapter,
+    MarkdownAdapter,
+    adapter_diagnostics,
+    adapter_for_uri,
+    get_adapter,
+)

c2s/__main__.py

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

c2s/_context_menu.py

@@ -0,0 +1,44 @@
+"""Windows context-menu integration for Cite2Site.
+
+Provides `c2s install-context-menu` and `c2s uninstall-context-menu` CLI
+commands.  Registers Cite2Site entries in the Windows Explorer right-click
+menu so users can look up citations and cite selections directly from any
+file.
+"""
+from __future__ import annotations
+
+
+def _menu_entries() -> list[dict[str, str]]:
+    """Return the context-menu entries to register."""
+    return [
+        {
+            "name": "Look up citations here",
+            "command": 'cmd /k c2s lookup-actions --artifact "%1" --start 0 --end 0',
+        },
+        {
+            "name": "Cite selection here",
+            "command": 'cmd /k c2s cite-selection --artifact "%1" --start 0 --end 0',
+        },
+    ]
+
+
+def install() -> None:
+    """Register Cite2Site in the Windows Explorer context menu."""
+    from context_menu import menus
+
+    entries = [
+        menus.ContextCommand(name=e["name"], command=e["command"])
+        for e in _menu_entries()
+    ]
+    menu = menus.ContextMenu(name="Cite2Site", type="FILES", entries=entries)
+    menu.compile()
+    print("Cite2Site added to Windows right-click menu.")
+    print("Right-click any file -> Cite2Site -> Look up citations here / Cite selection here")
+
+
+def uninstall() -> None:
+    """Remove Cite2Site from the Windows Explorer context menu."""
+    from context_menu import menus
+
+    menus.ContextMenu(name="Cite2Site", type="FILES", entries=[]).remove()
+    print("Cite2Site removed from Windows right-click menu.")

c2s/adapter.py

@@ -0,0 +1,436 @@
+from __future__ import annotations
+
+import abc
+import dataclasses
+from pathlib import Path
+from typing import Any
+
+from .core import (
+    C2SError,
+    Repo,
+    canonical_text,
+    evidence_for_text,
+    line_hashes,
+    line_number_at,
+    make_locator,
+    normalize_uri,
+    resolve_artifact_path,
+    sha256_json,
+    TEXT_CANON,
+)
+
+# ---------------------------------------------------------------------------
+# Adapter diagnostics — stable structured codes for adapter-level failures
+# ---------------------------------------------------------------------------
+
+_ADAPTER_DIAGNOSTICS = {
+    "E_ADAPTER_UNSUPPORTED": "the requested adapter is not installed or recognized",
+    "E_ADAPTER_UTF8": "artifact content is not valid UTF-8 text",
+    "E_ADAPTER_MISSING": "artifact file does not exist at the resolved path",
+    "E_ADAPTER_EMPTY_SELECTION": "selection range captured zero characters",
+    "E_ADAPTER_RANGE_INVALID": "selection range is outside artifact bounds",
+    "E_ADAPTER_AMBIGUOUS": "adapter cannot resolve a single authoritative evidence",
+    "E_ADAPTER_UNAVAILABLE": "artifact is temporarily unavailable (network, timeout, or converter failure)",
+}
+
+# ---------------------------------------------------------------------------
+# Adapter contract types
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass(frozen=True)
+class AdapterArtifact:
+    """Stable artifact identity produced by an adapter."""
+
+    adapter: str
+    uri: str
+    artifact_id: str
+
+
+# ---------------------------------------------------------------------------
+# Abstract adapter protocol
+# ---------------------------------------------------------------------------
+
+
+class BaseAdapter(abc.ABC):
+    """Protocol every Cite2Site adapter must fulfil.
+
+    Concrete adapters implement eight contract methods:
+      identify    – stable artifact identity
+      canonicalize – read artifact and return canonical text
+      evidence    – produce canonical evidence from selected text
+      locate      – produce unambiguous locator coordinates
+      observe     – read current artifact bytes at a locator (no mutation)
+      compare     – deterministic resolved/changed status
+      summarize   – metadata-safe human-readable range summary
+      privacy     – comply with the active publication privacy mode
+    """
+
+    # Subclasses override this.
+    name: str = "base"
+
+    # ------------------------------------------------------------------
+    # Contract methods (must be implemented)
+    # ------------------------------------------------------------------
+
+    @abc.abstractmethod
+    def identify(self, repo: Repo, uri: str) -> AdapterArtifact:
+        """Return stable artifact identity for *uri*."""
+
+    @abc.abstractmethod
+    def canonicalize(self, repo: Repo, uri: str) -> str:
+        """Read artifact and return canonical text.
+
+        Raises structured C2SError with an adapter-level diagnostic on failure.
+        """
+
+    @abc.abstractmethod
+    def evidence(self, selected_text: str) -> dict[str, Any]:
+        """Produce canonical evidence dict for *selected_text*."""
+
+    @abc.abstractmethod
+    def locate(self, source_text: str, start: int, end: int) -> dict[str, Any]:
+        """Produce an unambiguous locator from *start*/*end* scalar offsets."""
+
+    @abc.abstractmethod
+    def observe(self, repo: Repo, artifact: dict[str, Any], locator: dict[str, Any]) -> dict[str, Any]:
+        """Read current artifact content at *locator* without mutation.
+
+        Returns an evidence dict for the currently observed selection.
+        """
+
+    @abc.abstractmethod
+    def compare(self, accepted_evidence: dict[str, Any], observed_evidence: dict[str, Any]) -> str:
+        """Return 'resolved' or 'changed'.  'missing' and 'unsupported' are
+        determined externally by core.observe_status()."""
+
+    @abc.abstractmethod
+    def summarize(self, locator: dict[str, Any]) -> str:
+        """Return a metadata-safe human-readable range summary."""
+
+    @abc.abstractmethod
+    def privacy(self, citation: dict[str, Any], mode: str, policy: dict[str, Any]) -> None:
+        """Mutate *citation* in-place to comply with *mode*/*policy*.
+
+        The default implementation delegates to the core apply_privacy,
+        which is adapter-agnostic.  Adapters that need specialised
+        redaction (e.g. stripping structured fields) override this.
+        """
+
+    # ------------------------------------------------------------------
+    # Derived helpers (not part of the conformance surface)
+    # ------------------------------------------------------------------
+
+    def citation_id_for(self, artifact: AdapterArtifact, locator: dict[str, Any], evidence: dict[str, Any]) -> str:
+        return sha256_json(
+            {
+                "kind": "c2s.citation",
+                "artifact": {"adapter": artifact.adapter, "uri": artifact.uri, "artifact_id": artifact.artifact_id},
+                "locator": locator,
+                "accepted_evidence_hash": evidence["content_hash"],
+            }
+        )
+
+    def validate_selection(self, source_text: str, start: int, end: int) -> str:
+        """Return the selected text, or raise a structured diagnostic."""
+        if start < 0 or end < start or end > len(source_text):
+            raise C2SError(
+                "E_ADAPTER_RANGE_INVALID",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_RANGE_INVALID"],
+                start=start,
+                end=end,
+                length=len(source_text),
+            )
+        selected = source_text[start:end]
+        if selected == "":
+            raise C2SError(
+                "E_ADAPTER_EMPTY_SELECTION",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_EMPTY_SELECTION"],
+                start=start,
+                end=end,
+            )
+        return selected
+
+
+# ---------------------------------------------------------------------------
+# Filesystem text adapter — the canonical plain-text adapter
+# ---------------------------------------------------------------------------
+
+
+class FilesystemTextAdapter(BaseAdapter):
+    """Plain-text filesystem adapter (UTF-8, LF-normalised)."""
+
+    name = "filesystem-text"
+
+    # -- contract -------------------------------------------------------
+
+    def identify(self, repo: Repo, uri: str) -> AdapterArtifact:
+        path = resolve_artifact_path(repo, uri)
+        identity = {"adapter": self.name, "uri": normalize_uri(uri), "path": str(path)}
+        return AdapterArtifact(adapter=self.name, uri=normalize_uri(uri), artifact_id=sha256_json(identity))
+
+    def canonicalize(self, repo: Repo, uri: str) -> str:
+        path = resolve_artifact_path(repo, uri)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError as exc:
+            raise C2SError(
+                "E_ADAPTER_MISSING",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_MISSING"],
+                artifact=uri,
+            ) from exc
+        except UnicodeDecodeError as exc:
+            raise C2SError(
+                "E_ADAPTER_UTF8",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_UTF8"],
+                artifact=uri,
+            ) from exc
+        return canonical_text(raw)
+
+    def evidence(self, selected_text: str) -> dict[str, Any]:
+        return evidence_for_text(selected_text)
+
+    def locate(self, source_text: str, start: int, end: int) -> dict[str, Any]:
+        selected = self.validate_selection(source_text, start, end)
+        return make_locator(source_text, start, end)
+
+    def observe(self, repo: Repo, artifact: dict[str, Any], locator: dict[str, Any]) -> dict[str, Any]:
+        uri = str(artifact["uri"])
+        source = self.canonicalize(repo, uri)
+        start, end = int(locator["start"]), int(locator["end"])
+        if end > len(source):
+            raise C2SError(
+                "E_ADAPTER_RANGE_INVALID",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_RANGE_INVALID"],
+                artifact=uri,
+                start=start,
+                end=end,
+                length=len(source),
+            )
+        selected = source[start:end]
+        if selected == "":
+            raise C2SError(
+                "E_ADAPTER_EMPTY_SELECTION",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_EMPTY_SELECTION"],
+                artifact=uri,
+                start=start,
+                end=end,
+            )
+        return self.evidence(selected)
+
+    def compare(self, accepted_evidence: dict[str, Any], observed_evidence: dict[str, Any]) -> str:
+        if accepted_evidence["content_hash"] == observed_evidence["content_hash"]:
+            return "resolved"
+        return "changed"
+
+    def summarize(self, locator: dict[str, Any]) -> str:
+        if "start_line" in locator and "end_line" in locator:
+            return f"lines {locator['start_line']}-{locator['end_line']}"
+        return f"{locator['start']}-{locator['end']}"
+
+    def privacy(self, citation: dict[str, Any], mode: str, policy: dict[str, Any]) -> None:
+        # Delegate to core.apply_privacy — adapter-agnostic transform.
+        from .core import apply_privacy as _apply_privacy
+
+        _apply_privacy(citation, mode, policy)
+
+
+# ---------------------------------------------------------------------------
+# Markdown adapter — text semantics with explicit Markdown awareness marker
+# ---------------------------------------------------------------------------
+
+
+class MarkdownAdapter(FilesystemTextAdapter):
+    """Markdown adapter using text-line semantics.
+
+    Block-aware locators, summaries, and observation are not yet
+    implemented.  This adapter intentionally inherits the plain-text
+    contract until the block-level spec and test suite are delivered.
+    """
+
+    name = "markdown"
+
+
+# ---------------------------------------------------------------------------
+# Converter adapter — shells out to external format converters
+# ---------------------------------------------------------------------------
+#
+# One generic adapter, configured per file extension, replaces three
+# separate per-format adapters (DOCX, PDF, XLSX).  canonicalize() shells
+# out to a registered converter and treats stdout as canonical text;
+# evidence() / locate() / compare() reuse the filesystem-text code path.
+# identify() records converter name + version so a converter upgrade that
+# changes output is detectable, not a silent replay failure.
+
+
+class ConverterAdapter(FilesystemTextAdapter):
+    """Generic adapter backed by an external format converter.
+
+    Configured with a *name*, a list of *extensions* (e.g. ``[".docx"]``),
+    a *convert_cmd* list where ``{path}`` is replaced with the artifact
+    path, and a *version_cmd* list that prints the converter version.
+    """
+
+    name: str
+    extensions: tuple[str, ...]
+    convert_cmd: list[str]
+    version_cmd: list[str]
+
+    def __init__(
+        self,
+        name: str,
+        extensions: tuple[str, ...],
+        convert_cmd: list[str],
+        version_cmd: list[str],
+    ):
+        self.name = name
+        self.extensions = extensions
+        self.convert_cmd = convert_cmd
+        self.version_cmd = version_cmd
+        self._converter_version: str | None = None
+
+    def _detect_version(self) -> str:
+        """Run version_cmd and return stripped stdout, caching the result."""
+        if self._converter_version is None:
+            import subprocess
+            try:
+                r = subprocess.run(self.version_cmd, capture_output=True, text=True, timeout=10)
+                self._converter_version = r.stdout.strip() or r.stderr.strip() or "unknown"
+            except Exception:
+                self._converter_version = "unknown"
+        return self._converter_version
+
+    # -- contract overrides --------------------------------------------
+
+    def identify(self, repo: Repo, uri: str) -> AdapterArtifact:
+        path = resolve_artifact_path(repo, uri)
+        version = self._detect_version()
+        identity = {
+            "adapter": self.name,
+            "uri": normalize_uri(uri),
+            "path": str(path),
+            "converter": self.name,
+            "converter_version": version,
+        }
+        return AdapterArtifact(
+            adapter=self.name,
+            uri=normalize_uri(uri),
+            artifact_id=sha256_json(identity),
+        )
+
+    def canonicalize(self, repo: Repo, uri: str) -> str:
+        path = resolve_artifact_path(repo, uri)
+        if not path.exists():
+            raise C2SError(
+                "E_ADAPTER_MISSING",
+                _ADAPTER_DIAGNOSTICS["E_ADAPTER_MISSING"],
+                artifact=uri,
+            )
+        import subprocess
+        cmd = [str(path) if arg == "{path}" else arg for arg in self.convert_cmd]
+        try:
+            r = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        except FileNotFoundError as exc:
+            raise C2SError(
+                "E_ADAPTER_UNSUPPORTED",
+                f"converter '{self.convert_cmd[0]}' not found on PATH",
+                adapter=self.name,
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise C2SError(
+                "E_ADAPTER_UNAVAILABLE",
+                f"converter '{self.convert_cmd[0]}' timed out",
+                adapter=self.name,
+            ) from exc
+        if r.returncode != 0:
+            raise C2SError(
+                "E_ADAPTER_UTF8",
+                f"converter '{self.convert_cmd[0]}' failed: {r.stderr.strip() or 'exit ' + str(r.returncode)}",
+                adapter=self.name,
+            )
+        # Normalize line endings, same as filesystem-text
+        return canonical_text(r.stdout)
+
+    # evidence(), locate(), observe(), compare(), summarize(), privacy()
+    # are all inherited from FilesystemTextAdapter.
+
+
+# ---------------------------------------------------------------------------
+# Adapter registry
+# ---------------------------------------------------------------------------
+
+
+_CONVERTER_ADAPTERS: dict[str, BaseAdapter] = {}
+
+# Register pandoc adapter for .docx files (optional — converter must be on PATH)
+try:
+    _CONVERTER_ADAPTERS["pandoc"] = ConverterAdapter(
+        name="pandoc",
+        extensions=(".docx",),
+        convert_cmd=["pandoc", "-f", "docx", "-t", "plain", "--wrap=none", "{path}"],
+        version_cmd=["pandoc", "--version"],
+    )
+except Exception:
+    pass
+
+# Register pdftotext adapter for .pdf files (optional — converter must be on PATH)
+try:
+    _CONVERTER_ADAPTERS["pdftotext"] = ConverterAdapter(
+        name="pdftotext",
+        extensions=(".pdf",),
+        convert_cmd=["pdftotext", "-layout", "{path}", "-"],
+        version_cmd=["pdftotext", "-v"],
+    )
+except Exception:
+    pass
+
+# Register passthrough text-converter for testing (uses OS cat/type equivalent)
+_cat_cmd = ["python", "-c", "import sys; sys.stdout.write(open(sys.argv[1]).read())"]
+_cat_ver = ["python", "--version"]
+_CONVERTER_ADAPTERS["text-converter"] = ConverterAdapter(
+    name="text-converter",
+    extensions=(".txt", ".csv"),
+    convert_cmd=_cat_cmd + ["{path}"],
+    version_cmd=_cat_ver,
+)
+
+_SUPPORTED: dict[str, BaseAdapter] = {
+    "filesystem-text": FilesystemTextAdapter(),
+    "markdown": MarkdownAdapter(),
+    **_CONVERTER_ADAPTERS,
+}
+
+
+def get_adapter(name: str) -> BaseAdapter:
+    """Return the adapter instance for *name*.
+
+    Raises E_ADAPTER_UNSUPPORTED when *name* is not a supported adapter.
+    """
+    if name not in _SUPPORTED:
+        raise C2SError(
+            "E_ADAPTER_UNSUPPORTED",
+            _ADAPTER_DIAGNOSTICS["E_ADAPTER_UNSUPPORTED"],
+            adapter=name,
+            supported=sorted(_SUPPORTED.keys()),
+        )
+    return _SUPPORTED[name]
+
+
+def adapter_for_uri(uri: str, requested: str | None = None) -> str:
+    """Resolve the adapter name for *uri*, optionally overriding with *requested*."""
+    if requested:
+        get_adapter(requested)  # validates
+        return requested
+    lower = uri.lower()
+    if lower.endswith((".md", ".markdown")):
+        return "markdown"
+    if lower.endswith(".docx") and "pandoc" in _SUPPORTED:
+        return "pandoc"
+    if lower.endswith(".pdf") and "pdftotext" in _SUPPORTED:
+        return "pdftotext"
+    return "filesystem-text"
+
+
+def adapter_diagnostics() -> dict[str, str]:
+    """Return the stable adapter diagnostic code→message map (for docs/tests)."""
+    return dict(_ADAPTER_DIAGNOSTICS)

c2s/cli.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Callable
+
+from . import core
+from .adapter import _SUPPORTED as _ADAPTER_CHOICES  # noqa: F811 — registry
+
+_ADAPTER_NAMES = sorted(_ADAPTER_CHOICES.keys())
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise core.C2SError("E_USAGE", message)
+
+
+def emit(value: dict[str, Any]) -> int:
+    print(json.dumps(value, indent=2, sort_keys=True))
+    return 0 if value.get("ok", False) else 1
+
+
+def emit_jsonl(value: dict[str, Any]) -> int:
+    for citation in value["citations"]:
+        print(json.dumps(citation, sort_keys=True, separators=(",", ":"), ensure_ascii=False))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = JsonArgumentParser(prog="c2s")
+    parser.add_argument("--repo", default=".c2s", help="citation repository path")
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=JsonArgumentParser)
+
+    p_init = sub.add_parser("init")
+    p_init.add_argument("--force", action="store_true")
+    p_init.set_defaults(func=lambda args: core.init_repo(core.repo_from_arg(args.repo), force=args.force))
+
+    def add_actor(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--actor-kind", default="user", choices=["user", "agent", "machine"])
+        p.add_argument("--actor-id")
+
+    p_cite = sub.add_parser("cite-selection")
+    p_cite.add_argument("--artifact", required=True)
+    p_cite.add_argument("--adapter", choices=_ADAPTER_NAMES)
+    p_cite.add_argument("--start", required=True, type=int)
+    p_cite.add_argument("--end", required=True, type=int)
+    p_cite.add_argument("--expected-content-hash")
+    p_cite.add_argument("--handle")
+    p_cite.add_argument("--label")
+    p_cite.add_argument("--tag", action="append", default=[])
+    p_cite.add_argument("--note")
+    p_cite.add_argument("--handle-from-first-line", action="store_true")
+    add_actor(p_cite)
+    p_cite.set_defaults(func=core.cite_selection)
+
+    p_preflight = sub.add_parser("preflight-selection")
+    p_preflight.add_argument("--artifact", required=True)
+    p_preflight.add_argument("--adapter", choices=_ADAPTER_NAMES)
+    p_preflight.add_argument("--start", required=True, type=int)
+    p_preflight.add_argument("--end", required=True, type=int)
+    p_preflight.add_argument("--expected-content-hash")
+    p_preflight.add_argument("--handle")
+    p_preflight.add_argument("--label")
+    p_preflight.add_argument("--tag", action="append", default=[])
+    p_preflight.add_argument("--note")
+    p_preflight.add_argument("--handle-from-first-line", action="store_true")
+    p_preflight.set_defaults(func=core.preflight_selection)
+
+    p_batch = sub.add_parser("cite-batch")
+    p_batch.add_argument("--request", required=True)
+    add_actor(p_batch)
+    p_batch.set_defaults(func=core.cite_batch)
+
+    p_handle = sub.add_parser("set-handle")
+    p_handle.add_argument("--citation-id", required=True)
+    p_handle.add_argument("--handle", required=True)
+    p_handle.add_argument("--action", default="bind", choices=["bind", "rename", "alias", "retire"])
+    p_handle.add_argument("--previous-handle")
+    add_actor(p_handle)
+    p_handle.set_defaults(func=core.set_handle)
+
+    p_accept = sub.add_parser("accept-current")
+    p_accept.add_argument("--citation-id", required=True)
+    p_accept.add_argument("--expected-content-hash")
+    add_actor(p_accept)
+    p_accept.set_defaults(func=core.accept_current)
+
+    for command, func in [("retract", core.retract), ("restore", core.restore)]:
+        action = sub.add_parser(command)
+        action.add_argument("--citation-id", required=True)
+        add_actor(action)
+        action.set_defaults(func=func)
+
+    p_relocate = sub.add_parser("relocate")
+    p_relocate.add_argument("--citation-id", required=True)
+    p_relocate.add_argument("--artifact")
+    p_relocate.add_argument("--adapter", choices=_ADAPTER_NAMES)
+    p_relocate.add_argument("--start", required=True, type=int)
+    p_relocate.add_argument("--end", required=True, type=int)
+    p_relocate.add_argument("--expected-content-hash")
+    add_actor(p_relocate)
+    p_relocate.set_defaults(func=core.relocate)
+
+    p_note = sub.add_parser("note")
+    p_note.add_argument("--citation-id", required=True)
+    p_note.add_argument("--note", required=True)
+    add_actor(p_note)
+    p_note.set_defaults(func=core.note)
+
+    p_lookup = sub.add_parser("lookup-actions")
+    p_lookup.add_argument("--artifact", required=True)
+    p_lookup.add_argument("--start", required=True, type=int)
+    p_lookup.add_argument("--end", required=True, type=int)
+    p_lookup.add_argument("--privacy", default=None, choices=sorted(core.PRIVACY_MODES))
+    p_lookup.set_defaults(func=core.lookup_actions)
+
+    p_status = sub.add_parser("status")
+    p_status.add_argument("--privacy", default=None, choices=sorted(core.PRIVACY_MODES))
+    p_status.set_defaults(func=core.status)
+
+    p_citations = sub.add_parser("citations")
+    p_citations.add_argument("--artifact")
+    p_citations.add_argument("--handle")
+    p_citations.add_argument("--tag")
+    p_citations.add_argument("--status", choices=sorted(core.VALID_STATUSES))
+    p_citations.add_argument("--batch")
+    p_citations.add_argument("--privacy", default=None, choices=sorted(core.PRIVACY_MODES))
+    p_citations.add_argument("--format", default="json", choices=["json", "jsonl"])
+    p_citations.set_defaults(func=core.citations)
+
+    p_export = sub.add_parser("export")
+    p_export.add_argument("--privacy", default=None, choices=sorted(core.PRIVACY_MODES))
+    p_export.set_defaults(func=core.export)
+
+    p_check = sub.add_parser("check")
+    p_check.set_defaults(func=core.check)
+
+    # -- context-menu integration --
+    def _install_context_menu(_args: argparse.Namespace) -> dict[str, Any]:
+        from ._context_menu import install
+        install()
+        return {"ok": True}
+
+    def _uninstall_context_menu(_args: argparse.Namespace) -> dict[str, Any]:
+        from ._context_menu import uninstall
+        uninstall()
+        return {"ok": True}
+
+    p_cm_install = sub.add_parser("install-context-menu")
+    p_cm_install.set_defaults(func=_install_context_menu)
+
+    p_cm_uninstall = sub.add_parser("uninstall-context-menu")
+    p_cm_uninstall.set_defaults(func=_uninstall_context_menu)
+
+    try:
+        args = parser.parse_args(argv)
+        func: Callable[[argparse.Namespace], dict[str, Any]] = args.func
+        value = func(args)
+        return emit_jsonl(value) if args.command == "citations" and args.format == "jsonl" else emit(value)
+    except core.C2SError as exc:
+        print(json.dumps(exc.to_json(), indent=2, sort_keys=True), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())