peekview 0.1.0__tar.gz

peekview-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Peek data
+.peek/
+*.db
+*.db-wal
+*.db-shm
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Logs
+*.log

peekview-0.1.0/Makefile

@@ -0,0 +1,26 @@
+.PHONY: dev test test-cov lint build clean
+
+dev:
+	uvicorn peek.main:app --host 127.0.0.1 --port 8080 --reload
+
+test:
+	python -m pytest tests/ -v --tb=short
+
+test-cov:
+	python -m pytest tests/ -v --tb=short --cov=peek --cov-report=term-missing
+
+lint:
+	ruff check peek/ tests/
+	ruff format --check peek/ tests/
+
+format:
+	ruff check --fix peek/ tests/
+	ruff format peek/ tests/
+
+build:
+	pip install -e ".[test]"
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	rm -rf .pytest_cache .coverage htmlcov

peekview-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: peekview
+Version: 0.1.0
+Summary: A lightweight code & document formatting display service
+Project-URL: Homepage, https://github.com/randomgitsrc/peek
+Project-URL: Repository, https://github.com/randomgitsrc/peek
+Author: Peek Team
+License: MIT
+Keywords: agent,code,documentation,mcp,viewer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=23.2.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: sqlmodel>=0.0.14
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: httpx>=0.26.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Peek
+
+A lightweight code & document formatting display service.
+
+> Agent（AI）产出 → Peek 格式化 → 人类友好查看
+
+## 快速开始
+
+### 安装
+
+```bash
+pip install peek
+```
+
+### 启动服务
+
+```bash
+# 本地开发
+peek serve
+
+# 生产部署（指定端口和主机）
+peek serve --host 0.0.0.0 --port 8080
+```
+
+服务启动后，访问 http://localhost:8080 即可使用 Web 界面。
+
+## 命令行用法
+
+### 创建条目
+
+```bash
+# 从文件创建
+peek create file.txt -s "My document"
+
+# 从多文件创建
+peek create src/*.py -s "Python project" -t python -t cli
+
+# 从标准输入创建
+echo "print('hello')" | peek create -s "From stdin" --from-stdin
+
+# 指定自定义 slug
+peek create README.md -s "Documentation" --slug docs
+```
+
+### 查看条目
+
+```bash
+# 查看条目详情
+peek get my-entry
+
+# 列出入库（支持分页）
+peek list
+peek list --page 2 --per-page 50
+
+# 搜索条目（FTS5 全文搜索）
+peek list -q "python function"
+
+# 按标签过滤
+peek list -t python -t cli
+```
+
+### 删除条目
+
+```bash
+# 删除条目（会要求确认）
+peek delete my-entry
+
+# 强制删除（无需确认）
+peek delete my-entry --force
+```
+
+## 配置
+
+通过环境变量配置：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PEEK_DATA_DIR` | `~/.peek/data` | 文件存储目录 |
+| `PEEK_DB_PATH` | `~/.peek/peek.db` | SQLite 数据库路径 |
+| `PEEK_ALLOWED_PATHS` | `[]` | 允许读取的本地路径列表 |
+| `PEEK_HOST` | `127.0.0.1` | 服务绑定地址 |
+| `PEEK_PORT` | `8080` | 服务端口 |
+| `PEEK_API_KEY` | `` | API 认证密钥（可选） |
+| `PEEK_CORS_ORIGINS` | `http://localhost:5173` | CORS 允许来源 |
+
+### 配置文件
+
+也可以将配置写入 `.env` 文件：
+
+```bash
+PEEK_DATA_DIR=/var/peek/data
+PEEK_DB_PATH=/var/peek/peek.db
+PEEK_HOST=0.0.0.0
+PEEK_PORT=8080
+PEEK_API_KEY=your-secret-key
+```
+
+## 特性
+
+- 🎨 **代码高亮** - 基于 Shiki 的语法高亮，支持 100+ 语言
+- 📝 **Markdown 渲染** - 支持 GitHub 风格 Markdown
+- 🔍 **全文搜索** - 基于 SQLite FTS5 的高性能搜索
+- 📂 **多文件支持** - 单条目支持多文件，树形展示
+- 🌓 **主题切换** - 深色/浅色模式，自动跟随系统
+- 📱 **移动端适配** - 响应式设计，底部工具栏
+- 🔗 **URL 友好** - 支持 slug 和文件路径参数
+- 🔒 **安全防护** - 路径遍历防护、API 认证、XSS 过滤
+
+## 技术栈
+
+- **后端**: FastAPI + SQLModel + SQLite (FTS5)
+- **前端**: Vue 3 + Vite + Shiki + TypeScript
+- **CLI**: Click + Rich
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/randomgitsrc/peek.git
+cd peek/backend
+
+# 安装开发依赖
+pip install -e ".[test,dev]"
+
+# 运行测试
+make test
+
+# 格式化代码
+make format
+
+# 启动开发服务器
+make dev
+```
+
+## 许可证
+
+MIT License

peekview-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Peek
+
+A lightweight code & document formatting display service.
+
+> Agent（AI）产出 → Peek 格式化 → 人类友好查看
+
+## 快速开始
+
+### 安装
+
+```bash
+pip install peek
+```
+
+### 启动服务
+
+```bash
+# 本地开发
+peek serve
+
+# 生产部署（指定端口和主机）
+peek serve --host 0.0.0.0 --port 8080
+```
+
+服务启动后，访问 http://localhost:8080 即可使用 Web 界面。
+
+## 命令行用法
+
+### 创建条目
+
+```bash
+# 从文件创建
+peek create file.txt -s "My document"
+
+# 从多文件创建
+peek create src/*.py -s "Python project" -t python -t cli
+
+# 从标准输入创建
+echo "print('hello')" | peek create -s "From stdin" --from-stdin
+
+# 指定自定义 slug
+peek create README.md -s "Documentation" --slug docs
+```
+
+### 查看条目
+
+```bash
+# 查看条目详情
+peek get my-entry
+
+# 列出入库（支持分页）
+peek list
+peek list --page 2 --per-page 50
+
+# 搜索条目（FTS5 全文搜索）
+peek list -q "python function"
+
+# 按标签过滤
+peek list -t python -t cli
+```
+
+### 删除条目
+
+```bash
+# 删除条目（会要求确认）
+peek delete my-entry
+
+# 强制删除（无需确认）
+peek delete my-entry --force
+```
+
+## 配置
+
+通过环境变量配置：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PEEK_DATA_DIR` | `~/.peek/data` | 文件存储目录 |
+| `PEEK_DB_PATH` | `~/.peek/peek.db` | SQLite 数据库路径 |
+| `PEEK_ALLOWED_PATHS` | `[]` | 允许读取的本地路径列表 |
+| `PEEK_HOST` | `127.0.0.1` | 服务绑定地址 |
+| `PEEK_PORT` | `8080` | 服务端口 |
+| `PEEK_API_KEY` | `` | API 认证密钥（可选） |
+| `PEEK_CORS_ORIGINS` | `http://localhost:5173` | CORS 允许来源 |
+
+### 配置文件
+
+也可以将配置写入 `.env` 文件：
+
+```bash
+PEEK_DATA_DIR=/var/peek/data
+PEEK_DB_PATH=/var/peek/peek.db
+PEEK_HOST=0.0.0.0
+PEEK_PORT=8080
+PEEK_API_KEY=your-secret-key
+```
+
+## 特性
+
+- 🎨 **代码高亮** - 基于 Shiki 的语法高亮，支持 100+ 语言
+- 📝 **Markdown 渲染** - 支持 GitHub 风格 Markdown
+- 🔍 **全文搜索** - 基于 SQLite FTS5 的高性能搜索
+- 📂 **多文件支持** - 单条目支持多文件，树形展示
+- 🌓 **主题切换** - 深色/浅色模式，自动跟随系统
+- 📱 **移动端适配** - 响应式设计，底部工具栏
+- 🔗 **URL 友好** - 支持 slug 和文件路径参数
+- 🔒 **安全防护** - 路径遍历防护、API 认证、XSS 过滤
+
+## 技术栈
+
+- **后端**: FastAPI + SQLModel + SQLite (FTS5)
+- **前端**: Vue 3 + Vite + Shiki + TypeScript
+- **CLI**: Click + Rich
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/randomgitsrc/peek.git
+cd peek/backend
+
+# 安装开发依赖
+pip install -e ".[test,dev]"
+
+# 运行测试
+make test
+
+# 格式化代码
+make format
+
+# 启动开发服务器
+make dev
+```
+
+## 许可证
+
+MIT License

peekview-0.1.0/peek/__init__.py

@@ -0,0 +1,3 @@
+"""Peek - A lightweight code & document formatting display service."""
+
+__version__ = "0.1.0"

peekview-0.1.0/peek/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m peek."""
+
+from peek.cli import cli
+
+if __name__ == "__main__":
+    cli()

peekview-0.1.0/peek/api/__init__.py

@@ -0,0 +1 @@
+"""Peek API routes."""

peekview-0.1.0/peek/api/entries.py

@@ -0,0 +1,123 @@
+"""Entry CRUD API routes."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query, Request
+from fastapi.responses import JSONResponse
+
+from peek.models import CreateEntryRequest, EntryUpdate
+from peek.services.entry_service import EntryService, get_entry_service
+
+router = APIRouter(prefix="/api/v1/entries", tags=["entries"])
+
+
+def _get_service(request: Request) -> EntryService:
+    """Get EntryService from app state."""
+    return get_entry_service(request.app)
+
+
+@router.post("", status_code=201)
+async def create_entry(
+    data: CreateEntryRequest,
+    request: Request,
+    service: EntryService = Depends(_get_service),
+):
+    """Create a new entry. Returns 201 Created."""
+    # Convert files and dirs to dicts
+    files_data = []
+    for f in data.files:
+        file_dict = {}
+        if f.path is not None:
+            file_dict["path"] = f.path
+        if f.content is not None:
+            file_dict["content"] = f.content
+        if f.local_path is not None:
+            file_dict["local_path"] = f.local_path
+        files_data.append(file_dict)
+
+    dirs_data = []
+    for d in data.dirs:
+        dirs_data.append({"path": d.path})
+
+    return service.create_entry(
+        summary=data.summary,
+        slug=data.slug,
+        tags=data.tags,
+        files_data=files_data if files_data else None,
+        dirs_data=dirs_data if dirs_data else None,
+        expires_in=data.expires_in,
+    )
+
+
+@router.get("")
+async def list_entries(
+    request: Request,
+    q: str | None = Query(None),
+    tags: str | None = Query(None),
+    status: str | None = Query(None),
+    page: int = Query(1, ge=1),
+    per_page: int = Query(20, ge=1, le=100),
+    service: EntryService = Depends(_get_service),
+):
+    """List entries with search, filter, and pagination."""
+    tag_list = tags.split(",") if tags else None
+    return service.list_entries(q=q, tags=tag_list, status=status, page=page, per_page=per_page)
+
+
+@router.get("/{slug}")
+async def get_entry(
+    slug: str,
+    request: Request,
+    service: EntryService = Depends(_get_service),
+):
+    """Get entry details by slug."""
+    return service.get_entry(slug)
+
+
+@router.patch("/{slug}")
+async def update_entry(
+    slug: str,
+    data: EntryUpdate,
+    request: Request,
+    service: EntryService = Depends(_get_service),
+):
+    """Update an entry."""
+    # Convert add_files to dicts
+    add_files = None
+    if data.add_files:
+        add_files = []
+        for f in data.add_files:
+            file_dict = {}
+            if f.path is not None:
+                file_dict["path"] = f.path
+            if f.content is not None:
+                file_dict["content"] = f.content
+            if f.local_path is not None:
+                file_dict["local_path"] = f.local_path
+            add_files.append(file_dict)
+
+    # Convert add_dirs to dicts
+    add_dirs = None
+    if data.add_dirs:
+        add_dirs = [{"path": d.path} for d in data.add_dirs]
+
+    return service.update_entry(
+        slug=slug,
+        summary=data.summary,
+        status=data.status,
+        tags=data.tags,
+        add_files=add_files,
+        remove_file_ids=data.remove_file_ids,
+        add_dirs=add_dirs,
+    )
+
+
+@router.delete("/{slug}")
+async def delete_entry(
+    slug: str,
+    request: Request,
+    service: EntryService = Depends(_get_service),
+):
+    """Delete entry by slug."""
+    service.delete_entry(slug)
+    return {"ok": True}

peekview-0.1.0/peek/api/files.py

@@ -0,0 +1,114 @@
+"""File download and content API routes."""
+
+from __future__ import annotations
+
+import re
+
+from fastapi import APIRouter, Request
+from fastapi.responses import Response
+from sqlmodel import Session, select
+
+from peek.database import get_engine
+from peek.exceptions import NotFoundError
+from peek.models import Entry, File
+from peek.storage import StorageManager
+
+router = APIRouter(prefix="/api/v1/entries", tags=["files"])
+
+
+def _sanitize_filename(filename: str) -> str:
+    """Sanitize filename for Content-Disposition header to prevent injection.
+
+    Removes quotes, semicolons, and newlines that could break the header.
+    """
+    # Remove characters that could inject additional headers
+    sanitized = re.sub(r'[";\r\n]', "", filename)
+    # Limit length
+    if len(sanitized) > 200:
+        sanitized = sanitized[:200]
+    return sanitized
+
+
+def _language_to_content_type(language: str | None) -> str:
+    """Map language ID to Content-Type for inline display."""
+    _TYPE_MAP = {
+        "python": "text/x-python",
+        "javascript": "text/javascript",
+        "typescript": "text/typescript",
+        "html": "text/html",
+        "css": "text/css",
+        "json": "application/json",
+        "yaml": "text/yaml",
+        "xml": "text/xml",
+        "markdown": "text/markdown",
+        "sql": "text/x-sql",
+        "bash": "text/x-shellscript",
+        "go": "text/x-go",
+        "rust": "text/x-rust",
+        "java": "text/x-java",
+        "cpp": "text/x-c++src",
+        "text": "text/plain",
+    }
+    if language and language in _TYPE_MAP:
+        return _TYPE_MAP[language]
+    return "text/plain; charset=utf-8"
+
+
+@router.get("/{slug}/files/{file_id}")
+async def download_file(slug: str, file_id: int, request: Request):
+    """Download a single file (with Content-Disposition: attachment)."""
+    config = request.app.state.config
+    engine = get_engine(config)
+    storage = StorageManager(config=config)
+
+    with Session(engine) as session:
+        entry = session.exec(select(Entry).where(Entry.slug == slug)).first()
+        if not entry:
+            raise NotFoundError(f"Entry not found: {slug}")
+
+        file_record = session.exec(
+            select(File).where(File.id == file_id, File.entry_id == entry.id)
+        ).first()
+        if not file_record:
+            raise NotFoundError(f"File not found: {file_id}")
+
+        content = storage.read_file(entry.id, file_record.filename, file_record.path)
+        safe_name = _sanitize_filename(file_record.filename)
+        return Response(
+            content=content,
+            media_type="application/octet-stream",
+            headers={"Content-Disposition": f'attachment; filename="{safe_name}"'},
+        )
+
+
+@router.get("/{slug}/files/{file_id}/content")
+async def get_file_content(slug: str, file_id: int, request: Request):
+    """Get file content inline (raw text, no Content-Disposition).
+
+    Returns the file content with an appropriate Content-Type based on
+    language. No Content-Disposition header — suitable for inline display.
+    """
+    config = request.app.state.config
+    engine = get_engine(config)
+    storage = StorageManager(config=config)
+
+    with Session(engine) as session:
+        entry = session.exec(select(Entry).where(Entry.slug == slug)).first()
+        if not entry:
+            raise NotFoundError(f"Entry not found: {slug}")
+
+        file_record = session.exec(
+            select(File).where(File.id == file_id, File.entry_id == entry.id)
+        ).first()
+        if not file_record:
+            raise NotFoundError(f"File not found: {file_id}")
+
+    content = storage.read_file(entry.id, file_record.filename, file_record.path)
+
+    # Determine Content-Type from language
+    content_type = _language_to_content_type(file_record.language)
+    return Response(
+        content=content,
+        media_type=content_type,
+        # No Content-Disposition — inline display
+    )