Metadata-Version: 2.4
Name: capydocs
Version: 0.4.0
Summary: A lightweight web-based markdown document manager for your repository
Author: mjk
License-Expression: MIT
Keywords: markdown,docs,editor,web
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: click>=8.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fastmcp>=2.0.0
Provides-Extra: ai
Requires-Dist: openai>=1.0.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"

# capydocs

A lightweight, pip-installable web-based markdown document manager. Point it at any directory and manage your `.md` files through a clean dark-themed web UI with AI-powered text refinement.

## Features

- **File tree** — Browse `.md` files in a collapsible sidebar tree view
- **CodeMirror 6 editor** — Syntax-highlighted markdown editing
- **Full CRUD + Move** — Create, read, update, delete, and rename/move markdown files
- **Folder management** — Create and delete folders from the sidebar (+ Folder button, hover ✕ to delete, right-click context menu)
- **Drag and drop** — Move files between folders by dragging in the sidebar tree
- **Server-side search** — Search by filename and content with context snippets
- **AI text refinement** — Select text and refine it with OpenAI gpt-5-mini (concise, fix grammar, translate, change tone, or custom instructions)
- **MCP server** — Expose document management as MCP tools for AI agents
- **Keyboard shortcuts** — Ctrl/Cmd+S to save
- **Zero config** — `pip install` and run, no build step or database needed

## Quick Start

### Prerequisites
- Python 3.10+
- (Optional) OpenAI API key for AI features

### Installation & Run

```bash
# Install
pip install -e ".[ai]"

# Create a .env file with your OpenAI key (optional, for AI features)
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Serve a directory
capydocs --dir ./docs

# Open http://localhost:8000 in your browser
```

### CLI Options

```
capydocs [OPTIONS]

Options:
  --dir TEXT      Root directory to serve (default: current directory)
  --port INTEGER  Port number (default: 8000)
  --host TEXT     Host to bind to (default: 0.0.0.0)
  --reload        Enable auto-reload for development
  --help          Show help message
```

### Development Commands (Makefile)

```bash
make install    # pip install -e ".[dev,ai]"
make run        # Start server (port 8000)
make dev        # Start with auto-reload
make test       # Run pytest
make lint       # Run ruff check
make format     # Run ruff --fix
make build      # Build package (dist/)
make clean      # Remove build artifacts
```

## Capy Groom (AI Features)

AI-powered document grooming uses OpenAI gpt-5-mini. Set your API key in `.env`:

```bash
OPENAI_API_KEY=sk-...
```

### Usage
1. Open a file in the editor
2. Click the **🦫 Groom** button (or select text first for partial refinement)
3. Choose a preset or type a custom instruction
4. Review the side-by-side before/after comparison
5. Edit the result if needed, then click **Apply**

### Presets

| Preset | Description |
|--------|-------------|
| 📦 Compact | Summarize and remove unnecessary content |
| 🔧 Fix | Polish grammar, spelling, and awkward phrasing |
| 🇺🇸 English | Translate to English |
| 🇰🇷 Korean | Translate to Korean |

## Architecture

```
capydocs/
├── pyproject.toml              # Package metadata + CLI entry point
├── Makefile                    # Dev commands
├── src/capydocs/
│   ├── __init__.py             # Version
│   ├── cli.py                  # Click CLI + .env loading
│   ├── server.py               # FastAPI app factory
│   ├── mcp_server.py           # MCP server (FastMCP)
│   ├── routers/
│   │   ├── files.py            # File CRUD (GET/POST/PUT/DELETE)
│   │   ├── search.py           # Search endpoint
│   │   └── ai.py               # AI refinement endpoint
│   ├── services/
│   │   ├── filesystem.py       # File I/O + path traversal protection
│   │   ├── search.py           # Filename + content search
│   │   └── ai.py               # OpenAI gpt-5-mini integration
│   └── static/
│       ├── index.html          # SPA entry point
│       ├── css/style.css       # Dark theme (Catppuccin-inspired)
│       └── js/
│           ├── app.js          # Main app logic + toast notifications
│           ├── tree.js         # File tree component
│           ├── editor.js       # CodeMirror 6 wrapper
│           ├── ai.js           # AI refinement dialog UI
│           └── cm-bundle.js    # Pre-built CodeMirror bundle
└── tests/                      # 42 tests (pytest)
    ├── conftest.py
    ├── test_filesystem.py
    ├── test_files_api.py
    ├── test_search.py
    └── test_ai.py
```

### Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | FastAPI + uvicorn |
| Frontend | Vanilla JS + CodeMirror 6 (pre-built bundle) |
| CLI | Click + python-dotenv |
| AI | OpenAI SDK (gpt-5-mini) |
| Testing | pytest + httpx |
| Linting | ruff (E, F, I, UP, B, SIM, RUF) |

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/tree` | File tree |
| GET | `/api/files/{path}` | Read file |
| PUT | `/api/files/{path}` | Update file |
| POST | `/api/files/{path}` | Create file |
| PATCH | `/api/files/{path}` | Move/rename file |
| DELETE | `/api/files/{path}` | Delete file |
| POST | `/api/dirs/{path}` | Create directory |
| DELETE | `/api/dirs/{path}` | Delete directory |
| GET | `/api/search?q=` | Search files |
| POST | `/api/ai/refine` | AI text refinement |
| GET | `/api/ai/presets` | List AI presets |

## Design Decisions

- **No build step for frontend** — CodeMirror is pre-bundled via esbuild and shipped as a static asset. No npm/webpack needed at runtime.
- **File-system backed** — No database. Files are read/written directly to disk. What you see in the UI is what's on disk.
- **Path traversal protection** — All file paths are resolved and validated against the root directory before any I/O operation.
- **AI as optional** — Core editing works without any API key. AI features show a clear error message when no key is configured.
- **pip-installable** — Single `pip install` gives you a CLI tool. No Docker, no config files required.
- **Dark theme** — Catppuccin-inspired color scheme for comfortable long-session editing.

## Security

- Path traversal attacks are blocked by resolving all paths and verifying they stay within the configured root directory
- API keys are loaded from environment variables or `.env` files, never exposed to the frontend
- The AI refinement endpoint proxies requests through the server so client never sees the API key

## License

MIT
