docpybara 0.1.0__tar.gz

docpybara-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: docpybara
+Version: 0.1.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
+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
+Provides-Extra: ai
+Requires-Dist: openai>=1.0.0; extra == "ai"
+Requires-Dist: anthropic>=0.20.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"

docpybara-0.1.0/README.md

@@ -0,0 +1,168 @@
+# docpybara
+
+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.
+
+Built as a final project for Stanford CS146S: The Modern Software Developer.
+
+## Features
+
+- **File tree** — Browse `.md` files in a collapsible sidebar tree view
+- **CodeMirror 6 editor** — Syntax-highlighted markdown editing with formatting toolbar (bold, italic, heading, link, list)
+- **Full CRUD** — Create, read, update, and delete markdown files from the browser
+- **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)
+- **Save feedback** — Visual toast notifications and status indicators on save
+- **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
+docpybara --dir ./docs
+
+# Open http://localhost:8000 in your browser
+```
+
+### CLI Options
+
+```
+docpybara [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
+```
+
+## AI Features
+
+AI text refinement 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. Select text you want to refine
+3. Click the **AI** button in the toolbar
+4. Choose a preset or type a custom instruction
+5. Preview the result and click **Apply**
+
+### Presets
+
+| Preset | Description |
+|--------|-------------|
+| Concise | Make text more concise |
+| Fix grammar | Fix spelling and punctuation |
+| English | Translate to English |
+| Korean | Translate to Korean |
+| Formal | Professional tone |
+| Casual | Friendly tone |
+
+## Architecture
+
+```
+docpybara/
+├── pyproject.toml              # Package metadata + CLI entry point
+├── Makefile                    # Dev commands
+├── src/docpybara/
+│   ├── __init__.py             # Version
+│   ├── cli.py                  # Click CLI + .env loading
+│   ├── server.py               # FastAPI app factory
+│   ├── 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/                      # 25 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 |
+| DELETE | `/api/files/{path}` | Delete file |
+| 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

docpybara-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docpybara"
+version = "0.1.0"
+description = "A lightweight web-based markdown document manager for your repository"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "mjk" }]
+keywords = ["markdown", "docs", "editor", "web"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "fastapi>=0.111.0",
+    "uvicorn>=0.23.0",
+    "click>=8.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+ai = [
+    "openai>=1.0.0",
+    "anthropic>=0.20.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "httpx>=0.24.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+docpybara = "docpybara.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+docpybara = ["static/**/*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific rules
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["docpybara"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

docpybara-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docpybara-0.1.0/src/docpybara/__init__.py

@@ -0,0 +1,3 @@
+"""docpybara - A lightweight web-based markdown document manager."""
+
+__version__ = "0.1.0"

docpybara-0.1.0/src/docpybara/cli.py

@@ -0,0 +1,36 @@
+"""CLI entry point for docpybara."""
+
+import click
+import uvicorn
+
+
+@click.command()
+@click.option("--dir", "root_dir", default=".", help="Root directory to serve markdown files from")
+@click.option("--port", default=8000, help="Port to run the server on")
+@click.option("--host", default="0.0.0.0", help="Host to bind the server to")
+@click.option("--reload", is_flag=True, help="Enable auto-reload for development")
+def main(root_dir: str, port: int, host: str, reload: bool) -> None:
+    """docpybara - A lightweight web-based markdown document manager."""
+    import os
+    from pathlib import Path
+
+    # Load .env from the root_dir or current directory
+    for env_path in [Path(root_dir) / ".env", Path(".env")]:
+        if env_path.is_file():
+            from dotenv import load_dotenv
+
+            load_dotenv(env_path)
+            break
+
+    os.environ["DOCPYBARA_ROOT_DIR"] = os.path.abspath(root_dir)
+
+    click.echo(f"docpybara v0.1.0 serving '{os.path.abspath(root_dir)}'")
+    click.echo(f"Open http://{host}:{port} in your browser")
+
+    uvicorn.run(
+        "docpybara.server:create_app",
+        factory=True,
+        host=host,
+        port=port,
+        reload=reload,
+    )

docpybara-0.1.0/src/docpybara/routers/ai.py

@@ -0,0 +1,39 @@
+"""AI text refinement API endpoint."""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from docpybara.services.ai import PRESETS, refine_text
+
+router = APIRouter(tags=["ai"])
+
+
+class RefineRequest(BaseModel):
+    text: str
+    instruction: str = ""
+    preset: str | None = None
+
+
+class RefineResponse(BaseModel):
+    refined: str
+    model: str
+
+
+@router.post("/ai/refine", response_model=RefineResponse)
+async def api_refine(body: RefineRequest) -> RefineResponse:
+    """Refine selected text using AI."""
+    if not body.text.strip():
+        raise HTTPException(status_code=400, detail="Text cannot be empty")
+    try:
+        result = await refine_text(body.text, body.instruction, body.preset)
+        return RefineResponse(**result)
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e)) from None
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"AI service error: {e}") from None
+
+
+@router.get("/ai/presets")
+async def api_presets() -> dict[str, str]:
+    """Get available refinement presets."""
+    return PRESETS

docpybara-0.1.0/src/docpybara/routers/files.py

@@ -0,0 +1,48 @@
+"""File management API endpoints."""
+
+from typing import Any
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel
+
+from docpybara.services.filesystem import create_file, delete_file, get_tree, read_file, write_file
+
+router = APIRouter(tags=["files"])
+
+
+class FileContent(BaseModel):
+    content: str = ""
+
+
+@router.get("/tree")
+async def api_get_tree(request: Request) -> list[dict[str, Any]]:
+    """Get the markdown file tree."""
+    return get_tree(request.app.state.root_dir)
+
+
+@router.get("/files/{path:path}")
+async def api_read_file(path: str, request: Request) -> dict[str, str]:
+    """Read a markdown file."""
+    content = read_file(request.app.state.root_dir, path)
+    return {"path": path, "content": content}
+
+
+@router.put("/files/{path:path}")
+async def api_write_file(path: str, body: FileContent, request: Request) -> dict[str, str]:
+    """Update a markdown file."""
+    write_file(request.app.state.root_dir, path, body.content)
+    return {"path": path, "status": "saved"}
+
+
+@router.post("/files/{path:path}", status_code=201)
+async def api_create_file(path: str, body: FileContent, request: Request) -> dict[str, str]:
+    """Create a new markdown file."""
+    create_file(request.app.state.root_dir, path, body.content)
+    return {"path": path, "status": "created"}
+
+
+@router.delete("/files/{path:path}")
+async def api_delete_file(path: str, request: Request) -> dict[str, str]:
+    """Delete a markdown file."""
+    delete_file(request.app.state.root_dir, path)
+    return {"path": path, "status": "deleted"}

docpybara-0.1.0/src/docpybara/routers/search.py

@@ -0,0 +1,15 @@
+"""Search API endpoint."""
+
+from typing import Any
+
+from fastapi import APIRouter, Request
+
+from docpybara.services.search import search_files
+
+router = APIRouter(tags=["search"])
+
+
+@router.get("/search")
+async def api_search(q: str, request: Request) -> list[dict[str, Any]]:
+    """Search markdown files by filename and content."""
+    return search_files(request.app.state.root_dir, q)

docpybara-0.1.0/src/docpybara/server.py

@@ -0,0 +1,30 @@
+"""FastAPI application factory."""
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(title="docpybara", version="0.1.0")
+
+    root_dir = os.environ.get("DOCPYBARA_ROOT_DIR", ".")
+    app.state.root_dir = Path(root_dir).resolve()
+
+    # Register routers
+    from docpybara.routers.ai import router as ai_router
+    from docpybara.routers.files import router as files_router
+    from docpybara.routers.search import router as search_router
+
+    app.include_router(files_router, prefix="/api")
+    app.include_router(search_router, prefix="/api")
+    app.include_router(ai_router, prefix="/api")
+
+    # Serve static frontend files
+    static_dir = Path(__file__).parent / "static"
+    app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="static")
+
+    return app

docpybara-0.1.0/src/docpybara/services/ai.py

@@ -0,0 +1,55 @@
+"""AI text refinement service using OpenAI."""
+
+import os
+from typing import Any
+
+PRESETS: dict[str, str] = {
+    "concise": "Make this text more concise while preserving the meaning.",
+    "fix": "Fix grammar, spelling, and punctuation errors. Keep the original tone.",
+    "translate_en": "Translate this text to English. Preserve formatting.",
+    "translate_ko": "Translate this text to Korean. Preserve formatting.",
+    "formal": "Rewrite this text in a more formal, professional tone.",
+    "casual": "Rewrite this text in a more casual, friendly tone.",
+}
+
+MODEL = "gpt-5-mini"
+
+
+async def refine_text(
+    text: str,
+    instruction: str,
+    preset: str | None = None,
+) -> dict[str, Any]:
+    """Refine text using OpenAI gpt-5-mini."""
+    from openai import AsyncOpenAI
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise ValueError("No API key configured. Set OPENAI_API_KEY environment variable.")
+
+    if preset and preset in PRESETS:
+        instruction = PRESETS[preset]
+
+    if not instruction:
+        instruction = "Improve this text."
+
+    client = AsyncOpenAI(api_key=api_key)
+    response = await client.chat.completions.create(
+        model=MODEL,
+        messages=[
+            {
+                "role": "system",
+                "content": (
+                    "You are a writing assistant. "
+                    "The user will give you text and an instruction. "
+                    "Return ONLY the refined text, nothing else. "
+                    "Do not add explanations, preamble, or formatting wrappers."
+                ),
+            },
+            {"role": "user", "content": f"Instruction: {instruction}\n\nText:\n{text}"},
+        ],
+    )
+    return {
+        "refined": response.choices[0].message.content,
+        "model": MODEL,
+    }

docpybara-0.1.0/src/docpybara/services/filesystem.py

@@ -0,0 +1,84 @@
+"""Filesystem service for markdown file operations."""
+
+from pathlib import Path
+from typing import Any
+
+from fastapi import HTTPException
+
+
+def _validate_path(root_dir: Path, relative_path: str) -> Path:
+    """Validate and resolve a path, preventing path traversal attacks."""
+    resolved = (root_dir / relative_path).resolve()
+    if not str(resolved).startswith(str(root_dir)):
+        raise HTTPException(status_code=403, detail="Access denied: path traversal detected")
+    return resolved
+
+
+def get_tree(root_dir: Path) -> list[dict[str, Any]]:
+    """Get a recursive tree of markdown files under root_dir."""
+    if not root_dir.is_dir():
+        return []
+
+    def _build_tree(directory: Path) -> list[dict[str, Any]]:
+        entries: list[dict[str, Any]] = []
+        try:
+            items = sorted(directory.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except PermissionError:
+            return entries
+
+        for item in items:
+            if item.name.startswith("."):
+                continue
+            if item.is_dir():
+                children = _build_tree(item)
+                if children:
+                    entries.append({
+                        "name": item.name,
+                        "path": str(item.relative_to(root_dir)),
+                        "type": "directory",
+                        "children": children,
+                    })
+            elif item.suffix.lower() == ".md":
+                entries.append({
+                    "name": item.name,
+                    "path": str(item.relative_to(root_dir)),
+                    "type": "file",
+                })
+        return entries
+
+    return _build_tree(root_dir)
+
+
+def read_file(root_dir: Path, relative_path: str) -> str:
+    """Read a markdown file and return its content."""
+    file_path = _validate_path(root_dir, relative_path)
+    if not file_path.is_file():
+        raise HTTPException(status_code=404, detail=f"File not found: {relative_path}")
+    return file_path.read_text(encoding="utf-8")
+
+
+def write_file(root_dir: Path, relative_path: str, content: str) -> None:
+    """Write content to a markdown file."""
+    file_path = _validate_path(root_dir, relative_path)
+    if not file_path.is_file():
+        raise HTTPException(status_code=404, detail=f"File not found: {relative_path}")
+    file_path.write_text(content, encoding="utf-8")
+
+
+def create_file(root_dir: Path, relative_path: str, content: str = "") -> None:
+    """Create a new markdown file."""
+    if not relative_path.endswith(".md"):
+        relative_path += ".md"
+    file_path = _validate_path(root_dir, relative_path)
+    if file_path.exists():
+        raise HTTPException(status_code=409, detail=f"File already exists: {relative_path}")
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content, encoding="utf-8")
+
+
+def delete_file(root_dir: Path, relative_path: str) -> None:
+    """Delete a markdown file."""
+    file_path = _validate_path(root_dir, relative_path)
+    if not file_path.is_file():
+        raise HTTPException(status_code=404, detail=f"File not found: {relative_path}")
+    file_path.unlink()

docpybara-0.1.0/src/docpybara/services/search.py

@@ -0,0 +1,61 @@
+"""Search service for markdown files."""
+
+from pathlib import Path
+from typing import Any
+
+
+def search_files(root_dir: Path, query: str, max_results: int = 50) -> list[dict[str, Any]]:
+    """Search markdown files by filename and content."""
+    if not query.strip():
+        return []
+
+    query_lower = query.lower()
+    results: list[dict[str, Any]] = []
+
+    if not root_dir.is_dir():
+        return results
+
+    for md_file in sorted(root_dir.rglob("*.md")):
+        if md_file.name.startswith("."):
+            continue
+        # Skip hidden directories
+        if any(part.startswith(".") for part in md_file.relative_to(root_dir).parts):
+            continue
+
+        rel_path = str(md_file.relative_to(root_dir))
+        name_match = query_lower in md_file.name.lower()
+
+        try:
+            content = md_file.read_text(encoding="utf-8")
+        except (PermissionError, UnicodeDecodeError):
+            continue
+
+        content_lower = content.lower()
+        content_match = query_lower in content_lower
+
+        if name_match or content_match:
+            context = ""
+            if content_match:
+                idx = content_lower.index(query_lower)
+                start = max(0, idx - 40)
+                end = min(len(content), idx + len(query) + 40)
+                context = content[start:end].replace("\n", " ").strip()
+                if start > 0:
+                    context = "..." + context
+                if end < len(content):
+                    context = context + "..."
+
+            results.append({
+                "path": rel_path,
+                "name": md_file.name,
+                "name_match": name_match,
+                "content_match": content_match,
+                "context": context,
+            })
+
+        if len(results) >= max_results:
+            break
+
+    # Sort: name matches first, then content matches
+    results.sort(key=lambda r: (not r["name_match"], r["path"]))
+    return results