docmost-cli 0.4.0__tar.gz

docmost_cli-0.4.0/.claude/skills/docmost/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: docmost
+description: "Read, create, update, and search Docmost wiki pages. Use when the user wants to interact with their Docmost wiki -- reading documentation, creating pages, searching for information, or updating content."
+argument-hint: "[action] [details]"
+allowed-tools: "Bash(docmost-cli *)"
+---
+
+# Docmost Wiki Interaction
+
+You have access to `docmost-cli`, a CLI tool for managing Docmost wiki instances. Use it to read, create, update, search, and manage wiki content.
+
+## Prerequisites
+
+The user must have `docmost-cli` installed and configured (`docmost-cli config init`). Test with `docmost-cli config test` if unsure.
+
+## Command Reference
+
+### Reading Content
+
+```bash
+# List all spaces
+docmost-cli space list --json
+
+# List pages in a space
+docmost-cli page list <space-slug> --json
+
+# Get page content as Markdown
+docmost-cli page get <page-id>
+
+# Get page with YAML frontmatter (id, title, space, dates)
+docmost-cli page get <page-id> --meta
+
+# Search across all pages
+docmost-cli search query "<search-term>" --json
+
+# Search within a specific space
+docmost-cli search query "<search-term>" --space <space-slug> --json
+
+# Show page tree structure
+docmost-cli page list <space-slug> --tree
+```
+
+### Writing Content
+
+```bash
+# Create a page from inline Markdown
+docmost-cli page create <space-slug> --title "Page Title" --content "# Heading\n\nContent here"
+
+# Create a page from a file
+docmost-cli page create <space-slug> --title "Page Title" --file content.md
+
+# Update page title
+docmost-cli page update <page-id> --title "New Title"
+
+# Delete a page (use -y to skip confirmation)
+docmost-cli -y page delete <page-id>
+```
+
+### Other Operations
+
+```bash
+# Show current user info
+docmost-cli user me
+
+# Show workspace details
+docmost-cli workspace info
+
+# Add a comment to a page
+docmost-cli comment create <page-id> --content "Comment text"
+
+# List comments on a page
+docmost-cli comment list <page-id> --json
+
+# Export a page
+docmost-cli page export <page-id> --format md
+```
+
+## Workflow Patterns
+
+### Finding and Reading a Page
+
+1. List spaces: `docmost-cli space list --json`
+2. Find the space slug you need
+3. Search or list pages: `docmost-cli search query "topic" --json`
+4. Read the page: `docmost-cli page get <page-id>`
+
+### Creating Documentation for Code
+
+1. Analyze the code the user wants documented
+2. Write Markdown content
+3. Save to a temp file or use `--content` flag
+4. Create the page: `docmost-cli page create <space-slug> --title "Title" --content "..."`
+5. Report the page ID back to the user
+
+### Updating Existing Documentation
+
+1. Get current content: `docmost-cli page get <page-id>`
+2. Modify the Markdown content as needed
+3. Update: `docmost-cli page update <page-id> --title "Updated Title"`
+4. Note: Content update via REST may not be available on Community edition
+
+## Output Format
+
+- **Content commands** (`page get`): Raw Markdown to stdout — directly usable
+- **List commands** (`--json`): JSON array — parse with standard JSON tools
+- **Write commands** (`page create`, `delete`): Page ID to stdout, confirmation to stderr
+- **Always use `--json`** for list/search commands when you need to parse the output programmatically
+
+## Tips
+
+- Use `--json` flag on list commands to get parseable output
+- Page IDs are UUIDs like `019a2a69-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+- Space slugs are lowercase alphanumeric (e.g., `engineering`, `devtest`)
+- Use `-y` flag to skip confirmation prompts for automated workflows
+- Use `--verbose` for debugging connectivity issues
+
+For detailed examples, see [examples.md](examples.md).

docmost_cli-0.4.0/.claude/skills/docmost/examples.md

@@ -0,0 +1,85 @@
+# Docmost Skill Examples
+
+## Example 1: Read wiki docs to inform implementation
+
+User says: "Check the wiki for our API authentication docs"
+
+```bash
+# Search for relevant pages
+docmost-cli search query "authentication" --json
+
+# Read the page content
+docmost-cli page get 019a2a69-xxxx --meta
+```
+
+## Example 2: Create documentation from code
+
+User says: "Document the payment module in our engineering wiki"
+
+```bash
+# Create the page with generated Markdown
+docmost-cli page create engineering --title "Payment Module" --content "# Payment Module
+
+## Overview
+The payment module handles all billing operations...
+
+## API Endpoints
+- POST /payments/create
+- GET /payments/:id
+
+## Configuration
+Set STRIPE_KEY in environment variables."
+```
+
+## Example 3: Backup all pages in a space
+
+```bash
+# Get all page IDs
+docmost-cli page list engineering --json
+
+# For each page, export to file
+docmost-cli page export <page-id> --format md --output backup/<page-id>.md
+```
+
+## Example 4: Search and summarize
+
+User says: "What does our wiki say about deployment?"
+
+```bash
+# Search
+docmost-cli search query "deployment" --json
+
+# Read each relevant result
+docmost-cli page get <id-1>
+docmost-cli page get <id-2>
+```
+
+Then summarize the findings for the user.
+
+## Example 5: Create a page from a file in the repo
+
+User says: "Publish our README to the wiki"
+
+```bash
+docmost-cli page create engineering --title "Project README" --file README.md
+```
+
+## Example 6: Browse space structure
+
+```bash
+# See the full page hierarchy
+docmost-cli page list engineering --tree
+
+# List child pages of a specific page
+docmost-cli page children <parent-id> --json
+```
+
+## Example 7: Add review comments to a page
+
+```bash
+# Add a comment
+docmost-cli comment create <page-id> --content "Reviewed by Claude Code - looks good, minor typo in section 3"
+
+# List existing comments
+docmost-cli comment list <page-id> --json
+```

docmost_cli-0.4.0/.gitignore

@@ -0,0 +1,52 @@
+# Python bytecode / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# C extensions
+*.so
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Claude Code local settings (keep skills/ committed for team use)
+.claude/*
+!.claude/skills/
+
+# Environment / secrets
+.env
+.env.*
+config.toml

docmost_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 0.4.0 (2026-03-22)
+
+- Add `sync pull` command: download all pages from a space to local Markdown files with YAML frontmatter
+- Add `sync push` command: upload local changes to server (create, update, move pages)
+- Add `sync status` command: show changes between local files and last-pulled state
+- Edition-aware content updates: Enterprise uses REST content update (preserves page ID), Community uses safe create-then-delete (new page created and verified before old page removed)
+- Flat directory layout with `.docmost-manifest.json` tracking sync state and SHA-256 content hashes
+- `--dry-run` flag on push to preview changes without executing
+- `--delete` flag on push to remove server pages not found locally (opt-in safety)
+- `--force` flag on pull to overwrite existing synced data
+- Topological sort ensures parent pages are created before children
+- ID remapping: when Community edition forces new page IDs, frontmatter and manifest are updated automatically
+- 105 new tests (96 sync module + 9 CLI integration)
+
+## 0.3.1 (2026-03-22)
+
+- Fix `page list --tree` and `page children` on Community edition: use `/pages/sidebar-pages` instead of `/pages/children` (404 on v0.70.3)
+- Tree recursion: only fetch children for pages with `hasChildren: true` (eliminates ~40 wasted API calls on a 50-page space)
+- Narrow error handling in tree builder (auth failures no longer silently swallowed)
+- Reduce API calls in `page get` (fetch page info once, not twice)
+- Remove raw HTTP call from CLI layer (use API function instead)
+- Deduplicate UTF-8 stdio reconfigure into `_ensure_utf8_stdio()`
+- Use `build_body` helper consistently in all API functions
+- Remove dead code: unused models, unused parameter
+
+## 0.3.0 (2026-03-22)
+
+- Add `parentPageId` to `page list --json` output columns
+- Add `parent_id` to `page get --meta` YAML frontmatter
+- Add `--icon` flag to `page update` command
+- Add recursive tree fallback: `page list --tree` fills in missing children
+- Add "See also" cross-references to all page command help text
+- Fix `page children` and `--tree` on Community edition: use `/pages/sidebar-pages` instead of `/pages/children` (404 on v0.70.3)
+- Fix emoji/Unicode crash: move UTF-8 encoding to correct entry point
+- Fix `--parent` on `page create`: use fractional index position string
+- Fix `--content` escape sequences: `\n` and `\t` now work as newline/tab
+
+## 0.2.4 (2026-03-22)
+
+- Fix emoji/Unicode crash for real: move UTF-8 reconfigure from `__main__.py` to `cli/main.py` (the actual entry point used by `docmost-cli` script bypasses `__main__.py`)
+
+## 0.2.3 (2026-03-22)
+
+- Fix `--parent` on `page create`: send fractional index position string (Docmost requires 5-12 char string, not integer)
+- Fix emoji crash on all Windows terminals: remove `isatty()` guard, always reconfigure to UTF-8 on Windows
+- Fix `--content` escape sequences: `\n` and `\t` now interpreted as actual newline/tab
+- Position parameter on `page move` changed from `int` to `str` (fractional index format)
+
+## 0.2.2 (2026-03-22)
+
+- Fix `--parent` on `page create` silently ignored (import endpoint ignores parentPageId; now calls move_page as fallback)
+- Fix `--help` crash on Windows (`OSError` from Rich's LegacyWindowsRenderer on cp1252 consoles)
+- Fix `page get --meta` crash when page content contains emoji (✅❌⚠️📊)
+- Reconfigure stdout/stderr to UTF-8 at startup on Windows interactive terminals
+
+## 0.2.1 (2026-03-22)
+
+- Fix tree view crash on Windows with emoji page icons (cp1252 encoding)
+- Fix silent Enterprise endpoint probe leaking error messages on Community edition
+- Fix API endpoints discovered during live integration testing:
+  - `/spaces/list` → `/spaces`
+  - `/comments/list` → `/comments`
+  - `/pages/export` format `md` → `markdown`, response is ZIP not JSON
+  - Auth token extracted from `authToken` cookie (not `token`)
+  - Comment content JSON-stringified for API
+- Consolidate duplicated code: shared `extract_items`, `extract_id`, `build_body` helpers
+- Remove 6 dead stub files (-84 lines)
+- Add `post_raw()` to DocmostClient for binary/probe responses
+- Fix double file read in page import
+- Add Claude Code skill (`/docmost`) for wiki interaction
+- Prepare for PyPI: py.typed marker, CHANGELOG, dependency upper bounds, classifiers
+
+## 0.2.0 (2026-03-22)
+
+- Retry with exponential backoff for transient errors (429, 5xx)
+- `--verbose` HTTP debug logging (request/response to stderr)
+- Page duplicate, copy, children, history, export, import commands
+- Tree view (`--tree`) for page listing
+- Workspace info/members, user me, attachment search commands
+- Pagination auto-follow with safety guard (max 1000 iterations)
+- ProseMirror-to-Markdown converter (all block nodes and marks)
+- Claude Code skill (`/docmost`) for wiki interaction
+- Comprehensive README with command reference
+- MIT LICENSE file
+- Session cache file permissions (0600)
+- 175 tests, 0 lint errors
+
+## 0.1.0 (2026-03-22)
+
+- Initial release
+- Project scaffolding with typer CLI framework
+- Configuration system with TOML profiles and environment variable overrides
+- HTTP client with API key (Enterprise) and session (Community) auth auto-detection
+- Page CRUD: create (via import endpoint), read, update, delete, move
+- Space list, create, update
+- Comment list, create, update (ProseMirror JSON wrapping)
+- Full-text search with space filtering
+- Output helpers enforcing stdout/stderr separation
+- Edition-agnostic design (Community + Enterprise)
+- 50 tests with pytest + pytest-httpx

docmost_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md — Project Instructions for Claude Code
+
+## Project
+
+This is `docmost-cli`, a Python CLI tool for managing Docmost wiki instances from the terminal.
+Read `SPECIFICATION.md` for the full project specification, API endpoints, command structure, and architecture.
+
+## Tech Stack
+
+- Python ≥ 3.11, using `typer`, `httpx`, `rich`, `pydantic-settings`
+- Package manager: `uv` preferred, `pip` as fallback
+- Test framework: `pytest` with `pytest-httpx` for HTTP mocking
+
+## Development Commands
+
+```bash
+# Install in dev mode
+uv pip install -e ".[dev]"
+
+# Run the CLI
+python -m docmost_cli
+# or after install:
+docmost-cli
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=docmost_cli
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Code Style
+
+- Use type hints everywhere (Python 3.11+ syntax, e.g. `str | None` not `Optional[str]`)
+- Docstrings on all public functions (Google style)
+- Keep CLI commands thin — business logic lives in `api/` and `convert/` modules
+- Use pydantic models for all API request/response types
+- `httpx.Client` should be created once and reused (connection pooling)
+- All API calls go through `DocmostClient` — never raw httpx in the CLI layer
+- Use `__all__` exports in `__init__.py` files
+
+## Architecture Rules
+
+```
+cli/     → depends on api/, sync/, output/ (never the reverse)
+api/     → depends on models/, config/     (never on cli/)
+sync/    → depends on api/, output/        (manifest, frontmatter, diff are standalone)
+convert/ → standalone                      (no internal dependencies)
+output/  → formats data only               (no API calls, no business logic)
+         enforces stdout/stderr separation
+models/  → standalone pydantic models      (no dependencies)
+config/  → standalone                      (no dependencies except pydantic)
+```
+
+## Testing Approach
+
+- **Conversion tests**: ProseMirror ↔ Markdown using fixture files in `tests/fixtures/`
+- **API tests**: Mock HTTP responses with `pytest-httpx`
+- **CLI tests**: Use typer's `CliRunner` for end-to-end command testing
+- **Fixture pairs**: Every `.json` fixture has a matching `.md` expected output
+
+## Important Patterns
+
+- **Auth auto-detection**: Check for `api_key` first, then fall back to `email`+`password`
+- **ProseMirror content**: Always convert to Markdown for display; use `--raw` for JSON
+- **Pagination**: Cursor-based. Auto-follow until exhausted unless `--limit` is set
+- **Error handling**: Catch `httpx` exceptions → translate to user-friendly messages via `rich`
+- **Confirmations**: Destructive operations prompt unless `--yes` / `-y` is passed
+- **Page creation**: Prefer the import endpoint (server-side MD→ProseMirror) over client-side conversion
+
+### Output Strategy (no global `--json` flag)
+
+The CLI follows Unix stdout/stderr separation. There is no global `--json` flag.
+Each command category uses the format that fits its data shape:
+
+| Command type | stdout | stderr | Example |
+|---|---|---|---|
+| **Content** (`page get`) | Raw Markdown | nothing | `docmost-cli page get abc123 > page.md` |
+| **Content + meta** (`page get --meta`) | YAML frontmatter + Markdown | nothing | Parseable by any frontmatter tool |
+| **Lists** (`page list`, `search`, ...) | Rich table (default) or JSON array (`--json`) | nothing | `docmost-cli page list eng --json \| jq` |
+| **Writes** (`page create`, `delete`, ...) | Resource ID only | Confirmation message | `ID=$(docmost-cli page create ...)` |
+| **Sync status** (`sync status`) | Change summary | nothing | `docmost-cli sync status eng` |
+| **Sync push dry-run** (`sync push --dry-run`) | Action plan | nothing | `docmost-cli sync push eng --dry-run` |
+| **Sync ops** (`sync pull`, `sync push`) | nothing | Progress + summary | `docmost-cli sync pull eng --dir ./docs/` |
+| **Errors** | nothing | Error message | Exit codes: 0=ok, 1=error, 3=auth, 4=not-found |
+
+This means:
+- `docmost-cli page get <id>` output is directly pipeable as Markdown
+- `docmost-cli page list <space> --json` is directly parseable by jq or Claude Code
+- `PAGE_ID=$(docmost-cli page create ...)` captures just the ID with no extra parsing
+- Human-readable messages never pollute captured output
+
+## Key Reference Files
+
+- `SPECIFICATION.md` — Full project spec (commands, API endpoints, architecture)
+- `src/docmost_cli/api/client.py` — Central HTTP client, auth logic
+- `src/docmost_cli/convert/` — ProseMirror ↔ Markdown converters
+- `tests/fixtures/` — ProseMirror JSON + expected Markdown pairs
+- `man/man1/` — Man pages in groff format (one hub + one per command group)
+
+## When Starting a New Feature
+
+1. Check `SPECIFICATION.md` section 4 for the command signature
+2. Check `SPECIFICATION.md` section 5.2 for the API endpoint
+3. Create/update the pydantic model in `models/`
+4. Implement the API method in `api/`
+5. Wire up the CLI command in `cli/`
+6. Add tests (API mock + CLI runner)
+7. Update the implementation phases checklist in `SPECIFICATION.md`
+8. Update the corresponding man page in `man/man1/`