bookstack-cli 0.1.0__tar.gz

bookstack_cli-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: bookstack-cli
+Version: 0.1.0
+Summary: CLI for coding agents to interact with a BookStack wiki via its REST API
+Author: Michael Zehrer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mzehrer/bookstack-cli
+Project-URL: Source, https://github.com/mzehrer/bookstack-cli
+Project-URL: Issues, https://github.com/mzehrer/bookstack-cli/issues
+Project-URL: Documentation, https://github.com/mzehrer/bookstack-cli#readme
+Keywords: bookstack,wiki,cli,api,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.36.2; extra == "dev"
+Requires-Dist: ruff>=0.15.19; extra == "dev"
+
+# bookstack-cli
+
+[![Python](https://img.shields.io/badge/python-≥3.14-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+
+CLI for coding agents to interact with a [BookStack](https://www.bookstackapp.com/) wiki via its REST API. All output is JSON — built for LLM pipelines, not humans.
+
+```bash
+bookstack books list | jq '. | length'
+bookstack pages get 42 | jq '.html[:200]'
+bookstack search query "api docs" | jq '.[] | {name, type, score}'
+bookstack test
+```
+
+## Install
+
+```bash
+# One-liner (no clone needed)
+uv tool install bookstack-cli          # from PyPI, once published
+# or from source:
+# uv tool install git+https://github.com/mzehrer/bookstack-cli.git
+
+# Or clone for development
+cd bookstack-cli
+make init          # or: uv sync
+```
+
+## Setup
+
+```bash
+bookstack auth           # interactive — prompts for URL, token, secret
+
+# If public web URL differs from API (e.g. behind OAuth proxy):
+bookstack auth --resolve-url https://wiki.public.example.com
+```
+
+### Config File
+
+Saved to `~/.config/bookstack-cli/config.toml`:
+
+```toml
+[connection]
+url = "http://10.0.0.1:8080"                    # API endpoint (internal)
+resolve_url = "https://wiki.public.example.com"  # public web URL (optional)
+token_id = "<your-token-id>"
+token_secret = "<your-token-secret>"
+```
+
+`resolve_url` is optional — defaults to `url` if not set.
+
+### Env Vars (override file)
+
+```bash
+export BOOKSTACK_URL=http://10.0.0.1:8080
+export BOOKSTACK_RESOLVE_URL=https://wiki.example.com
+export BOOKSTACK_TOKEN_ID=<your-token-id>
+export BOOKSTACK_TOKEN_SECRET=<your-token-secret>
+```
+
+Precedence: env vars > config file > error.
+
+[See auth docs →](docs/authentication.md)
+
+## Usage
+
+```
+$ bookstack --help
+
+╭─ Commands ───────────────────────────────────────╮
+│ auth         Save connection credentials.         │
+│ config       Manage connection config.            │
+│ test         Test connection to BookStack.        │
+│ shelves      Manage bookshelves.                  │
+│ books        Manage books.                        │
+│ chapters     Manage chapters.                     │
+│ pages        Manage pages.                        │
+│ attachments  Manage attachments.                  │
+│ users        Manage users (admin).                │
+│ roles        Manage roles (admin).                │
+│ search       Search content.                      │
+╰───────────────────────────────────────────────────╯
+```
+
+### Common Workflows
+
+```bash
+# Test connection
+bookstack test
+
+# List all books
+bookstack books list
+
+# Get a specific page
+bookstack pages get 42
+
+# Create a page from file
+bookstack pages create "My Page" --book-id 1 --markdown-file content.md
+
+# Pipe multi-line content
+cat content.md | bookstack pages create "Piped Page" --book-id 1
+
+# Append text to existing page
+bookstack pages update 42 --append "New section at the end"
+
+# Resolve web URL to page
+bookstack pages resolve-url "https://wiki/books/my-book/page/my-page"
+
+# Import markdown with images
+bookstack pages import --file article.md --book-id 1 --name "Article"
+
+# Search across all content
+bookstack search query "installation guide"
+
+# List attachments on a page
+bookstack attachments list --page-id 10
+
+# Upload a file attachment
+bookstack attachments upload --name "Report" --page-id 42 --file report.pdf
+
+# Create a shelf and assign books
+bookstack shelves create "Dev Docs"
+bookstack shelves update 1 "Dev Docs" --books "10,20,30"
+
+# Update entity
+bookstack books update 1 "New Title"
+```
+
+## Features
+
+| Feature | Status |
+|---|---|
+| Shelves CRUD (+ book assignment) | ✅ |
+| Books CRUD | ✅ |
+| Chapters CRUD | ✅ |
+| Pages CRUD (partial update, append, move) | ✅ |
+| Markdown import with image handling | ✅ |
+| Web URL → API ID resolution | ✅ |
+| Attachments (link + file upload) | ✅ |
+| Search across content | ✅ |
+| Users/Roles (admin) | ✅ |
+| Async HTTP with retry/backoff | ✅ |
+| Auto-pagination (client-side filtering) | ✅ |
+| Config test / connection check | ✅ |
+| JSON-only output | ✅ |
+
+## Project Layout
+
+```
+bookstack-cli/
+├── bookstack_cli/
+│   ├── client.py        # HTTP client, auth, rate-limit, pagination
+│   ├── config.py        # Env vars → ~/.config/bookstack-cli/config.toml
+│   ├── exceptions.py    # Typed error hierarchy
+│   ├── models.py        # Pydantic models for all entities
+│   ├── main.py          # Typer CLI entry point
+│   └── resources/       # One module per entity
+│       ├── books.py
+│       ├── chapters.py
+│       ├── pages.py
+│       ├── shelves.py
+│       ├── attachments.py
+│       ├── search.py
+│       ├── users.py
+│       ├── roles.py
+│       ├── revisions.py
+│       └── tags.py
+├── tests/               # 130+ tests
+├── docs/                # Detailed docs
+├── skill/               # Pi agent skill
+├── Makefile             # init/test/lint/format/run
+└── pyproject.toml
+```
+
+## Documentation
+
+| File | What |
+|---|---|
+| [docs/overview.md](docs/overview.md) | Architecture, goals, scope |
+| [docs/authentication.md](docs/authentication.md) | Token setup, env config, security |
+| [docs/api-reference.md](docs/api-reference.md) | All endpoints, schemas, pagination |
+| [docs/integration-guide.md](docs/integration-guide.md) | Hacking BookStack, injections, webhooks |
+| [docs/research.md](docs/research.md) | Raw API research findings |
+| [skill/SKILL.md](skill/SKILL.md) | Agent skill for pi/coding agents |
+| [AGENT.md](AGENT.md) | TDD protocol for this project |
+
+## Design
+
+- **Async from day one** — `httpx.AsyncClient` with retry + exponential backoff on 429s
+- **Pydantic v2** — typed models for every entity, validated responses
+- **Agent-friendly output** — everything is JSON via stdout, no interactive prompts
+- **Resource-per-file** — one module per entity, consistent `list/get/create/update/delete` signatures
+- **Config cascade** — env vars > `~/.config/bookstack-cli/config.toml` > error
+- **TDD** — 130 tests, red/green/refactor cycle (see [AGENT.md](AGENT.md))
+
+## License
+
+MIT

bookstack_cli-0.1.0/README.md

@@ -0,0 +1,197 @@
+# bookstack-cli
+
+[![Python](https://img.shields.io/badge/python-≥3.14-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+
+CLI for coding agents to interact with a [BookStack](https://www.bookstackapp.com/) wiki via its REST API. All output is JSON — built for LLM pipelines, not humans.
+
+```bash
+bookstack books list | jq '. | length'
+bookstack pages get 42 | jq '.html[:200]'
+bookstack search query "api docs" | jq '.[] | {name, type, score}'
+bookstack test
+```
+
+## Install
+
+```bash
+# One-liner (no clone needed)
+uv tool install bookstack-cli          # from PyPI, once published
+# or from source:
+# uv tool install git+https://github.com/mzehrer/bookstack-cli.git
+
+# Or clone for development
+cd bookstack-cli
+make init          # or: uv sync
+```
+
+## Setup
+
+```bash
+bookstack auth           # interactive — prompts for URL, token, secret
+
+# If public web URL differs from API (e.g. behind OAuth proxy):
+bookstack auth --resolve-url https://wiki.public.example.com
+```
+
+### Config File
+
+Saved to `~/.config/bookstack-cli/config.toml`:
+
+```toml
+[connection]
+url = "http://10.0.0.1:8080"                    # API endpoint (internal)
+resolve_url = "https://wiki.public.example.com"  # public web URL (optional)
+token_id = "<your-token-id>"
+token_secret = "<your-token-secret>"
+```
+
+`resolve_url` is optional — defaults to `url` if not set.
+
+### Env Vars (override file)
+
+```bash
+export BOOKSTACK_URL=http://10.0.0.1:8080
+export BOOKSTACK_RESOLVE_URL=https://wiki.example.com
+export BOOKSTACK_TOKEN_ID=<your-token-id>
+export BOOKSTACK_TOKEN_SECRET=<your-token-secret>
+```
+
+Precedence: env vars > config file > error.
+
+[See auth docs →](docs/authentication.md)
+
+## Usage
+
+```
+$ bookstack --help
+
+╭─ Commands ───────────────────────────────────────╮
+│ auth         Save connection credentials.         │
+│ config       Manage connection config.            │
+│ test         Test connection to BookStack.        │
+│ shelves      Manage bookshelves.                  │
+│ books        Manage books.                        │
+│ chapters     Manage chapters.                     │
+│ pages        Manage pages.                        │
+│ attachments  Manage attachments.                  │
+│ users        Manage users (admin).                │
+│ roles        Manage roles (admin).                │
+│ search       Search content.                      │
+╰───────────────────────────────────────────────────╯
+```
+
+### Common Workflows
+
+```bash
+# Test connection
+bookstack test
+
+# List all books
+bookstack books list
+
+# Get a specific page
+bookstack pages get 42
+
+# Create a page from file
+bookstack pages create "My Page" --book-id 1 --markdown-file content.md
+
+# Pipe multi-line content
+cat content.md | bookstack pages create "Piped Page" --book-id 1
+
+# Append text to existing page
+bookstack pages update 42 --append "New section at the end"
+
+# Resolve web URL to page
+bookstack pages resolve-url "https://wiki/books/my-book/page/my-page"
+
+# Import markdown with images
+bookstack pages import --file article.md --book-id 1 --name "Article"
+
+# Search across all content
+bookstack search query "installation guide"
+
+# List attachments on a page
+bookstack attachments list --page-id 10
+
+# Upload a file attachment
+bookstack attachments upload --name "Report" --page-id 42 --file report.pdf
+
+# Create a shelf and assign books
+bookstack shelves create "Dev Docs"
+bookstack shelves update 1 "Dev Docs" --books "10,20,30"
+
+# Update entity
+bookstack books update 1 "New Title"
+```
+
+## Features
+
+| Feature | Status |
+|---|---|
+| Shelves CRUD (+ book assignment) | ✅ |
+| Books CRUD | ✅ |
+| Chapters CRUD | ✅ |
+| Pages CRUD (partial update, append, move) | ✅ |
+| Markdown import with image handling | ✅ |
+| Web URL → API ID resolution | ✅ |
+| Attachments (link + file upload) | ✅ |
+| Search across content | ✅ |
+| Users/Roles (admin) | ✅ |
+| Async HTTP with retry/backoff | ✅ |
+| Auto-pagination (client-side filtering) | ✅ |
+| Config test / connection check | ✅ |
+| JSON-only output | ✅ |
+
+## Project Layout
+
+```
+bookstack-cli/
+├── bookstack_cli/
+│   ├── client.py        # HTTP client, auth, rate-limit, pagination
+│   ├── config.py        # Env vars → ~/.config/bookstack-cli/config.toml
+│   ├── exceptions.py    # Typed error hierarchy
+│   ├── models.py        # Pydantic models for all entities
+│   ├── main.py          # Typer CLI entry point
+│   └── resources/       # One module per entity
+│       ├── books.py
+│       ├── chapters.py
+│       ├── pages.py
+│       ├── shelves.py
+│       ├── attachments.py
+│       ├── search.py
+│       ├── users.py
+│       ├── roles.py
+│       ├── revisions.py
+│       └── tags.py
+├── tests/               # 130+ tests
+├── docs/                # Detailed docs
+├── skill/               # Pi agent skill
+├── Makefile             # init/test/lint/format/run
+└── pyproject.toml
+```
+
+## Documentation
+
+| File | What |
+|---|---|
+| [docs/overview.md](docs/overview.md) | Architecture, goals, scope |
+| [docs/authentication.md](docs/authentication.md) | Token setup, env config, security |
+| [docs/api-reference.md](docs/api-reference.md) | All endpoints, schemas, pagination |
+| [docs/integration-guide.md](docs/integration-guide.md) | Hacking BookStack, injections, webhooks |
+| [docs/research.md](docs/research.md) | Raw API research findings |
+| [skill/SKILL.md](skill/SKILL.md) | Agent skill for pi/coding agents |
+| [AGENT.md](AGENT.md) | TDD protocol for this project |
+
+## Design
+
+- **Async from day one** — `httpx.AsyncClient` with retry + exponential backoff on 429s
+- **Pydantic v2** — typed models for every entity, validated responses
+- **Agent-friendly output** — everything is JSON via stdout, no interactive prompts
+- **Resource-per-file** — one module per entity, consistent `list/get/create/update/delete` signatures
+- **Config cascade** — env vars > `~/.config/bookstack-cli/config.toml` > error
+- **TDD** — 130 tests, red/green/refactor cycle (see [AGENT.md](AGENT.md))
+
+## License
+
+MIT

bookstack_cli-0.1.0/bookstack_cli/__init__.py

@@ -0,0 +1,3 @@
+"""bookstack-cli: CLI tool for coding agents to interact with BookStack wiki."""
+
+__version__ = "0.1.0"

bookstack_cli-0.1.0/bookstack_cli/client.py

@@ -0,0 +1,211 @@
+"""Async HTTP client for BookStack API with auth, retry, pagination."""
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from bookstack_cli.config import get_config
+from bookstack_cli.exceptions import (
+    BookStackRateLimitError,
+    map_status_to_error,
+)
+
+logger = logging.getLogger(__name__)
+
+BASE_DELAY = 1.0
+MAX_RETRIES = 5
+MAX_PAGE_SIZE = 500
+
+
+class BookStackClient:
+    """Async HTTP client for BookStack REST API.
+
+    Handles:
+    - Auth header injection (Token token_id:token_secret)
+    - Rate-limit retry with exponential backoff
+    - Auto-pagination via async generator
+    - Error mapping to typed exceptions
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token_id: str | None = None,
+        token_secret: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if base_url and token_id and token_secret:
+            self._base_url = base_url.rstrip("/")
+            self._token_id = token_id
+            self._token_secret = token_secret
+        else:
+            cfg = get_config()
+            self._base_url = cfg.url
+            self._token_id = cfg.token_id
+            self._token_secret = cfg.token_secret
+
+        auth_header_value = f"Token {self._token_id}:{self._token_secret}"
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": auth_header_value,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout=httpx.Timeout(timeout),
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "BookStackClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def __enter__(self) -> "BookStackClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        loop.run_until_complete(self.close())
+
+    # ------------------------------------------------------------------
+    # Request with retry
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        retry_count: int = 0,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Send HTTP request with rate-limit retry."""
+        url = f"/api/{path.lstrip('/')}"
+        # Remove Content-Type for multipart (httpx sets correct boundary)
+        has_files = "files" in kwargs
+        if has_files:
+            old_ct = self._client.headers.pop("Content-Type", None)
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        finally:
+            if has_files and old_ct is not None:
+                self._client.headers["Content-Type"] = old_ct
+
+        if response.status_code == 429 and retry_count < MAX_RETRIES:
+            retry_after = _parse_retry_after(response)
+            delay = max(retry_after, BASE_DELAY * (2**retry_count))
+            logger.warning(
+                "Rate limited. Retry %d/%d after %.1fs",
+                retry_count + 1,
+                MAX_RETRIES,
+                delay,
+            )
+            await asyncio.sleep(delay)
+            return await self._request(method, path, retry_count + 1, **kwargs)
+
+        if response.is_error:
+            _raise_for_status(response)
+
+        return response
+
+    # ------------------------------------------------------------------
+    # CRUD helpers
+    # ------------------------------------------------------------------
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """GET request returning parsed JSON."""
+        response = await self._request("GET", path, params=params)
+        return response.json()
+
+    async def get_raw(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """GET request returning raw response (e.g. for binary downloads)."""
+        return await self._request("GET", path, params=params)
+
+    async def post(
+        self, path: str, json: dict[str, Any] | None = None, data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """POST request returning parsed JSON."""
+        response = await self._request("POST", path, json=json, data=data)
+        return response.json()
+
+    async def put(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """PUT request returning parsed JSON."""
+        response = await self._request("PUT", path, json=json)
+        return response.json()
+
+    async def delete(self, path: str) -> None:
+        """DELETE request."""
+        await self._request("DELETE", path)
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    async def paginate(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        page_size: int = 100,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Iterate over all pages of a list endpoint.
+
+        Yields individual items from ``data`` across all pages.
+        """
+        params = dict(params or {})
+        params.setdefault("count", min(page_size, MAX_PAGE_SIZE))
+        page = 1
+
+        while True:
+            params["page"] = page
+            data = await self.get(path, params=params)
+            items: list[dict[str, Any]] = data.get("data", [])
+            for item in items:
+                yield item
+
+            total: int = data.get("total", 0)
+            per_page = data.get("per_page")
+            if per_page is None:
+                per_page = len(items) or page_size
+            if page * per_page >= total:
+                break
+            page += 1
+
+
+def _parse_retry_after(response: httpx.Response) -> float:
+    """Extract Retry-After header value as float."""
+    val = response.headers.get("Retry-After", "1")
+    try:
+        return float(val)
+    except ValueError:
+        return 1.0
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP status to typed BookStack exception."""
+    try:
+        body = response.json()
+        error = body.get("error", {})
+        message = str(error.get("message", response.reason_phrase))
+        validation = error.get("validation")
+        if validation:
+            details = "; ".join(
+                f"{k}: {', '.join(v)}" for k, v in validation.items()
+            )
+            message = f"{message} ({details})"
+    except Exception:
+        message = response.reason_phrase or "Unknown error"
+
+    raise map_status_to_error(response.status_code, message)