@purpleraven/hits 0.2.0

package/hits_core/api/routes/handover.py

@@ -0,0 +1,117 @@
+"""Handover API routes - project-scoped session handover endpoints.
+
+These endpoints enable AI tools to:
+1. Get a structured handover summary for a specific project
+2. List all projects with activity
+3. Get project statistics
+
+Typical flow:
+  Session ending → POST /api/work-log (record work)
+  Session starting → GET /api/handover?project_path=... (get context)
+"""
+
+from typing import Any, Optional
+from pathlib import Path
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from hits_core.service.handover_service import HandoverService
+
+
+router = APIRouter()
+
+_service: Optional[HandoverService] = None
+
+
+def get_service() -> HandoverService:
+    global _service
+    if _service is None:
+        _service = HandoverService()
+    return _service
+
+
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+
+
+@router.get("/handover", response_model=APIResponse)
+async def get_handover(
+    project_path: str = Query(..., description="Absolute path to the project directory"),
+    format: str = Query("dict", description="Output format: 'dict' (JSON) or 'text' (markdown)"),
+    recent_count: int = Query(20, ge=1, le=100, description="Number of recent logs to include"),
+):
+    """Get a handover summary for a specific project.
+
+    This is the primary endpoint for session continuity. When an AI tool
+    starts a new session on a project, it calls this endpoint to get
+    all relevant context from previous sessions.
+
+    The project_path is used to scope all data to the specific project,
+    so different projects get completely independent handovers.
+    """
+    service = get_service()
+
+    # Validate path exists
+    if not Path(project_path).exists():
+        return APIResponse(
+            success=False,
+            error=f"Project path does not exist: {project_path}",
+        )
+
+    try:
+        summary = await service.get_handover(
+            project_path=project_path,
+            recent_count=recent_count,
+        )
+
+        if format == "text":
+            return APIResponse(
+                success=True,
+                data={"text": summary.to_text()},
+            )
+
+        return APIResponse(success=True, data=summary.to_dict())
+
+    except Exception as e:
+        return APIResponse(success=False, error=str(e))
+
+
+@router.get("/handover/projects", response_model=APIResponse)
+async def list_projects():
+    """List all projects that have recorded work logs.
+
+    Returns project paths with aggregated statistics, sorted by last activity.
+    Useful for discovering which projects have accumulated context.
+    """
+    service = get_service()
+
+    try:
+        projects = await service.list_projects()
+        return APIResponse(success=True, data=projects)
+    except Exception as e:
+        return APIResponse(success=False, error=str(e))
+
+
+@router.get("/handover/project-stats", response_model=APIResponse)
+async def get_project_stats(
+    project_path: str = Query(..., description="Absolute path to the project directory"),
+):
+    """Get aggregated statistics for a specific project.
+
+    Returns counts, tags, performers, files modified, etc.
+    Lighter than full handover - use this for quick project overview.
+    """
+    service = get_service()
+
+    try:
+        from hits_core.storage.file_store import FileStorage
+        storage = FileStorage()
+        stats = await storage.get_project_summary(
+            str(Path(project_path).resolve())
+        )
+        return APIResponse(success=True, data=stats)
+    except Exception as e:
+        return APIResponse(success=False, error=str(e))

package/hits_core/api/routes/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health_check():
+    return {"success": True, "data": {"status": "ok"}, "error": None}

package/hits_core/api/routes/knowledge.py

@@ -0,0 +1,177 @@
+"""Knowledge category API routes.
+
+These routes expose the KnowledgeService (config-based categories)
+through the API, enabling the web UI to manage knowledge categories
+and their nodes per-project.
+
+Endpoints:
+- GET    /api/knowledge/categories        → List all categories with nodes
+- POST   /api/knowledge/category          → Create a new category
+- PUT    /api/knowledge/category/{name}   → Update a category
+- DELETE /api/knowledge/category/{name}   → Delete a category
+- POST   /api/knowledge/category/{name}/nodes      → Add node
+- PUT    /api/knowledge/category/{name}/nodes/{idx} → Update node
+- DELETE /api/knowledge/category/{name}/nodes/{idx} → Delete node
+"""
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel, Field
+
+from hits_core.service.knowledge_service import KnowledgeService, KnowledgeNode
+from hits_core.auth.dependencies import require_auth
+
+
+router = APIRouter()
+
+_service: Optional[KnowledgeService] = None
+
+
+def get_service() -> KnowledgeService:
+    global _service
+    if _service is None:
+        _service = KnowledgeService()
+    return _service
+
+
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+
+
+# --- Models ---
+
+class CategoryCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    icon: str = Field("📁", max_length=4)
+
+
+class CategoryUpdate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    icon: Optional[str] = Field(None, max_length=4)
+
+
+class NodeCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=200)
+    layer: str = Field("what", pattern=r"^(why|how|what)$")
+    type: str = Field("url", pattern=r"^(url|shell)$")
+    action: str = Field("")
+    negative_path: bool = Field(False)
+
+
+class NodeUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=200)
+    layer: Optional[str] = Field(None, pattern=r"^(why|how|what)$")
+    type: Optional[str] = Field(None, pattern=r"^(url|shell)$")
+    action: Optional[str] = None
+    negative_path: Optional[bool] = None
+
+
+# --- Endpoints ---
+
+@router.get("/knowledge/categories", response_model=APIResponse)
+async def list_categories(user: dict = Depends(require_auth)):
+    """List all knowledge categories with their nodes."""
+    service = get_service()
+    categories = service.list_categories()
+    return APIResponse(
+        success=True,
+        data=[cat.to_dict() for cat in categories],
+    )
+
+
+@router.post("/knowledge/category", response_model=APIResponse)
+async def create_category(body: CategoryCreate, user: dict = Depends(require_auth)):
+    """Create a new knowledge category."""
+    service = get_service()
+    cat = service.add_category(body.name, body.icon)
+    if cat is None:
+        return APIResponse(success=False, error="Category already exists")
+    return APIResponse(success=True, data=cat.to_dict())
+
+
+@router.put("/knowledge/category/{category_name}", response_model=APIResponse)
+async def update_category(
+    category_name: str,
+    body: CategoryUpdate,
+    user: dict = Depends(require_auth),
+):
+    """Update a category's name and/or icon."""
+    service = get_service()
+    success = service.update_category(category_name, body.name, body.icon)
+    if not success:
+        return APIResponse(success=False, error="Category not found")
+    return APIResponse(success=True, data={"name": body.name})
+
+
+@router.delete("/knowledge/category/{category_name}", response_model=APIResponse)
+async def delete_category(category_name: str, user: dict = Depends(require_auth)):
+    """Delete a category and all its nodes."""
+    service = get_service()
+    success = service.delete_category(category_name)
+    if not success:
+        return APIResponse(success=False, error="Category not found")
+    return APIResponse(success=True, data={"deleted": category_name})
+
+
+@router.post("/knowledge/category/{category_name}/nodes", response_model=APIResponse)
+async def add_node(
+    category_name: str,
+    body: NodeCreate,
+    user: dict = Depends(require_auth),
+):
+    """Add a node to a category."""
+    service = get_service()
+    node = KnowledgeNode(
+        name=body.name,
+        layer=body.layer,
+        type=body.type,
+        action=body.action,
+        negative_path=body.negative_path,
+    )
+    success = service.add_node(category_name, node)
+    if not success:
+        return APIResponse(success=False, error="Category not found")
+    return APIResponse(success=True, data=node.to_dict())
+
+
+@router.put("/knowledge/category/{category_name}/nodes/{node_index}", response_model=APIResponse)
+async def update_node(
+    category_name: str,
+    node_index: int,
+    body: NodeUpdate,
+    user: dict = Depends(require_auth),
+):
+    """Update a specific node in a category."""
+    service = get_service()
+    existing = service.get_node(category_name, node_index)
+    if existing is None:
+        return APIResponse(success=False, error="Node not found")
+
+    updated = KnowledgeNode(
+        name=body.name or existing.name,
+        layer=body.layer or existing.layer,
+        type=body.type or existing.type,
+        action=body.action if body.action is not None else existing.action,
+        negative_path=body.negative_path if body.negative_path is not None else existing.negative_path,
+    )
+    success = service.update_node(category_name, node_index, updated)
+    if not success:
+        return APIResponse(success=False, error="Failed to update node")
+    return APIResponse(success=True, data=updated.to_dict())
+
+
+@router.delete("/knowledge/category/{category_name}/nodes/{node_index}", response_model=APIResponse)
+async def delete_node(
+    category_name: str,
+    node_index: int,
+    user: dict = Depends(require_auth),
+):
+    """Delete a node from a category."""
+    service = get_service()
+    success = service.delete_node(category_name, node_index)
+    if not success:
+        return APIResponse(success=False, error="Node not found")
+    return APIResponse(success=True, data={"deleted_index": node_index})

package/hits_core/api/routes/node.py

@@ -0,0 +1,121 @@
+from typing import Any, Optional
+from uuid import uuid4
+
+from fastapi import APIRouter, Query, HTTPException
+from pydantic import BaseModel
+
+from hits_core.service.tree_service import TreeService
+from hits_core.models.node import Node, NodeLayer, NodeType
+
+
+router = APIRouter()
+
+_service: Optional[TreeService] = None
+
+
+def get_service() -> TreeService:
+    global _service
+    if _service is None:
+        _service = TreeService()
+    return _service
+
+
+class NodeCreate(BaseModel):
+    tree_id: str
+    layer: str
+    title: str
+    description: Optional[str] = None
+    node_type: Optional[str] = "standard"
+    parent_id: Optional[str] = None
+    action: Optional[str] = None
+    action_type: Optional[str] = None
+    metadata: Optional[dict] = None
+
+
+class NodeUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    node_type: Optional[str] = None
+    action: Optional[str] = None
+    action_type: Optional[str] = None
+    metadata: Optional[dict] = None
+
+
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+
+
+@router.post("/node", response_model=APIResponse)
+async def create_node(body: NodeCreate):
+    service = get_service()
+    
+    tree = await service.get_tree(body.tree_id)
+    if tree is None:
+        return APIResponse(success=False, error="Tree not found")
+    
+    node = Node(
+        id=str(uuid4())[:8],
+        layer=NodeLayer(body.layer),
+        title=body.title,
+        description=body.description,
+        node_type=NodeType(body.node_type or "standard"),
+        parent_id=body.parent_id,
+        action=body.action,
+        action_type=body.action_type,
+        metadata=body.metadata or {},
+    )
+    
+    success = await service.add_node(body.tree_id, node)
+    if not success:
+        return APIResponse(success=False, error="Failed to add node")
+    
+    return APIResponse(success=True, data=node.model_dump())
+
+
+@router.put("/node/{node_id}", response_model=APIResponse)
+async def update_node(
+    node_id: str,
+    tree_id: str = Query(...),
+    body: NodeUpdate = None,
+):
+    service = get_service()
+    
+    node = await service.get_node(tree_id, node_id)
+    if node is None:
+        return APIResponse(success=False, error="Node not found")
+    
+    if body.title is not None:
+        node.title = body.title
+    if body.description is not None:
+        node.description = body.description
+    if body.node_type is not None:
+        node.node_type = NodeType(body.node_type)
+    if body.action is not None:
+        node.action = body.action
+    if body.action_type is not None:
+        node.action_type = body.action_type
+    if body.metadata is not None:
+        node.metadata = body.metadata
+    
+    tree = await service.get_tree(tree_id)
+    if tree:
+        tree.nodes[node_id] = node
+        await service.save_tree(tree)
+    
+    return APIResponse(success=True, data=node.model_dump())
+
+
+@router.delete("/node/{node_id}", response_model=APIResponse)
+async def delete_node(
+    node_id: str,
+    tree_id: str = Query(...),
+):
+    service = get_service()
+    
+    node = await service.remove_node(tree_id, node_id)
+    if node is None:
+        return APIResponse(success=False, error="Node not found or failed to delete")
+    
+    return APIResponse(success=True, data={"id": node_id})

package/hits_core/api/routes/work_log.py

@@ -0,0 +1,174 @@
+from datetime import datetime
+from typing import Optional, Any
+from uuid import uuid4
+
+from fastapi import APIRouter, Query, HTTPException
+from pydantic import BaseModel
+
+from hits_core.storage.file_store import FileStorage
+from hits_core.models.work_log import WorkLog, WorkLogSource, WorkLogResultType
+
+
+router = APIRouter()
+
+_storage: Optional[FileStorage] = None
+
+
+def get_storage() -> FileStorage:
+    global _storage
+    if _storage is None:
+        _storage = FileStorage()
+    return _storage
+
+
+class WorkLogCreate(BaseModel):
+    source: str
+    performed_by: str
+    request_text: Optional[str] = None
+    request_by: Optional[str] = None
+    result_type: Optional[str] = "none"
+    result_ref: Optional[str] = None
+    result_data: Optional[dict] = None
+    context: Optional[str] = None
+    tags: Optional[list[str]] = None
+    project_path: Optional[str] = None
+    node_id: Optional[str] = None
+    category: Optional[str] = None
+
+
+class WorkLogUpdate(BaseModel):
+    context: Optional[str] = None
+    tags: Optional[list[str]] = None
+    category: Optional[str] = None
+    node_id: Optional[str] = None
+
+
+class APIResponse(BaseModel):
+    success: bool
+    data: Optional[Any] = None
+    error: Optional[str] = None
+
+
+@router.post("/work-log", response_model=APIResponse)
+async def create_work_log(body: WorkLogCreate):
+    storage = get_storage()
+    
+    log = WorkLog(
+        id=str(uuid4())[:8],
+        source=WorkLogSource(body.source),
+        performed_by=body.performed_by,
+        request_text=body.request_text,
+        request_by=body.request_by,
+        result_type=WorkLogResultType(body.result_type or "none"),
+        result_ref=body.result_ref,
+        result_data=body.result_data,
+        context=body.context,
+        tags=body.tags or [],
+        project_path=body.project_path,
+        node_id=body.node_id,
+        category=body.category,
+    )
+    
+    success = await storage.save_work_log(log)
+    if not success:
+        return APIResponse(success=False, error="Failed to save work log")
+    
+    return APIResponse(success=True, data=log.model_dump())
+
+
+@router.get("/work-log/{log_id}", response_model=APIResponse)
+async def get_work_log(log_id: str):
+    storage = get_storage()
+    log = await storage.load_work_log(log_id)
+    
+    if log is None:
+        return APIResponse(success=False, error="Work log not found")
+    
+    return APIResponse(success=True, data=log.model_dump())
+
+
+@router.put("/work-log/{log_id}", response_model=APIResponse)
+async def update_work_log(log_id: str, body: WorkLogUpdate):
+    storage = get_storage()
+    log = await storage.load_work_log(log_id)
+    
+    if log is None:
+        return APIResponse(success=False, error="Work log not found")
+    
+    if body.context is not None:
+        log.context = body.context
+    if body.tags is not None:
+        log.tags = body.tags
+    if body.category is not None:
+        log.category = body.category
+    if body.node_id is not None:
+        log.node_id = body.node_id
+    
+    success = await storage.save_work_log(log)
+    if not success:
+        return APIResponse(success=False, error="Failed to update work log")
+    
+    return APIResponse(success=True, data=log.model_dump())
+
+
+@router.delete("/work-log/{log_id}", response_model=APIResponse)
+async def delete_work_log(log_id: str):
+    storage = get_storage()
+    success = await storage.delete_work_log(log_id)
+    
+    if not success:
+        return APIResponse(success=False, error="Failed to delete work log")
+    
+    return APIResponse(success=True, data={"id": log_id})
+
+
+@router.get("/work-logs", response_model=APIResponse)
+async def list_work_logs(
+    source: Optional[str] = Query(None),
+    performed_by: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    project_path: Optional[str] = Query(None, description="Filter by project path"),
+    limit: int = Query(100, ge=1, le=1000),
+):
+    storage = get_storage()
+    
+    since_dt = None
+    if since:
+        try:
+            since_dt = datetime.fromisoformat(since)
+        except ValueError:
+            return APIResponse(success=False, error="Invalid since format. Use ISO format.")
+    
+    logs = await storage.list_work_logs(
+        source=source,
+        performed_by=performed_by,
+        since=since_dt,
+        project_path=project_path,
+        limit=limit,
+    )
+    
+    return APIResponse(
+        success=True,
+        data=[log.model_dump() for log in logs]
+    )
+
+
+@router.get("/work-logs/search", response_model=APIResponse)
+async def search_work_logs(
+    q: str = Query(..., description="Search query"),
+    project_path: Optional[str] = Query(None, description="Filter by project path"),
+    limit: int = Query(50, ge=1, le=200),
+):
+    """Search work logs by keyword, optionally scoped to a project."""
+    storage = get_storage()
+    
+    logs = await storage.search_work_logs(
+        query=q,
+        project_path=project_path,
+        limit=limit,
+    )
+    
+    return APIResponse(
+        success=True,
+        data=[log.model_dump() for log in logs]
+    )