deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/skills.py

@@ -0,0 +1,315 @@
+"""
+Skills API Router
+=================
+
+CRUD endpoints for account-shared and workspace-owned SKILL.md packages.
+The optional ``skill_workspace`` selector is validated at authentication.
+
+Mounted at ``/api/skills``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from deeptutor.multi_user.context import get_current_user
+from deeptutor.multi_user.skill_access import (
+    assigned_skill_detail,
+    assigned_skill_ids,
+    assigned_skill_infos,
+)
+from deeptutor.services.skill import get_skill_service as get_account_skill_service
+from deeptutor.services.skill.service import (
+    InvalidSkillNameError,
+    InvalidTagError,
+    SkillExistsError,
+    SkillImportError,
+    SkillNotFoundError,
+    SkillReadOnlyError,
+    TagExistsError,
+    TagNotFoundError,
+)
+
+
+def get_skill_service():
+    from deeptutor.services.skill.runtime import library_workspace, workspace_skill_service
+
+    workspace_id = library_workspace.get()
+    return workspace_skill_service(workspace_id) if workspace_id else get_account_skill_service()
+
+
+router = APIRouter()
+
+
+class CreateSkillRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=64)
+    description: str = ""
+    content: str = ""
+    tags: list[str] = Field(default_factory=list)
+
+
+class UpdateSkillRequest(BaseModel):
+    description: str | None = None
+    content: str | None = None
+    rename_to: str | None = None
+    tags: list[str] | None = None
+
+
+class InstallSkillRequest(BaseModel):
+    """Install a hub skill into the caller's own skill layer.
+
+    ``ref`` is a ``<hub>:<slug>[@version]`` reference (the bare hub prefix
+    defaults to ``eduhub``). The web "import from EduHub" flow always builds an
+    ``eduhub:`` ref so a spoofed bridge message can't redirect the install to an
+    arbitrary registry.
+    """
+
+    ref: str = Field(..., min_length=1, max_length=256)
+    name: str | None = None
+    force: bool = False
+    allow_unverified: bool = False
+
+
+class CreateTagRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=32)
+
+
+class RenameTagRequest(BaseModel):
+    rename_to: str = Field(..., min_length=1, max_length=32)
+
+
+# ── tag routes (declared before `/{name}` so they are not shadowed) ──
+
+
+@router.get("/tags/list")
+async def list_tags() -> dict[str, list[str]]:
+    service = get_skill_service()
+    return {"tags": service.list_tags()}
+
+
+@router.post("/tags/create")
+async def create_tag(payload: CreateTagRequest) -> dict[str, str]:
+    service = get_skill_service()
+    try:
+        tag = service.create_tag(payload.name)
+    except TagExistsError as exc:
+        raise HTTPException(status_code=409, detail=f"Tag already exists: {exc}")
+    except InvalidTagError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"name": tag}
+
+
+@router.put("/tags/{tag}")
+async def rename_tag(tag: str, payload: RenameTagRequest) -> dict[str, str]:
+    service = get_skill_service()
+    try:
+        new_tag = service.rename_tag(tag, payload.rename_to)
+    except TagNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Tag not found: {tag}")
+    except TagExistsError as exc:
+        raise HTTPException(status_code=409, detail=f"Tag already exists: {exc}")
+    except InvalidTagError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"name": new_tag}
+
+
+@router.delete("/tags/{tag}")
+async def delete_tag(tag: str) -> dict[str, str]:
+    service = get_skill_service()
+    try:
+        service.delete_tag(tag)
+    except TagNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Tag not found: {tag}")
+    except InvalidTagError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"status": "deleted", "name": tag}
+
+
+# ── skill routes ───────────────────────────────────────────────────
+
+
+@router.get("/list")
+async def list_skills() -> dict[str, list[dict[str, object]]]:
+    service = get_skill_service()
+    own_items = [info.to_dict() for info in service.list_skills()]
+    user = get_current_user()
+    from deeptutor.services.skill.runtime import library_workspace
+
+    if user.is_admin or library_workspace.get():
+        return {"skills": own_items}
+    own_names = {item.get("name") for item in own_items}
+    merged = list(own_items)
+    for assigned in assigned_skill_infos(user.id):
+        if assigned.get("name") in own_names:
+            continue
+        merged.append(assigned)
+    return {"skills": merged}
+
+
+# ── hub browse (in-app EduHub skill browser; declared before `/{name}`) ──
+
+
+@router.get("/hub/catalog")
+async def hub_catalog(hub: str = "eduhub", q: str = "", limit: int = 50) -> dict[str, object]:
+    """Proxy a skill hub's public catalog for the in-app browser.
+
+    The web "Import from EduHub" panel renders these rows in DeepTutor's own
+    UI — no embedded iframe, no login — so users can browse, search, and
+    one-click download skills. Returns ``web_url`` (the hub's site origin) so
+    the panel can offer a "view on EduHub" link out.
+    """
+    import asyncio
+
+    from deeptutor.services.skill.hub import ClawHubProvider, HubError, get_hub_provider
+
+    try:
+        provider = get_hub_provider(hub)
+    except HubError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if not isinstance(provider, ClawHubProvider):
+        raise HTTPException(status_code=400, detail=f"Hub `{hub}` does not support browsing.")
+    try:
+        skills = await asyncio.to_thread(provider.catalog, query=q, limit=limit)
+    except HubError as exc:
+        raise HTTPException(status_code=502, detail=str(exc))
+    return {"hub": provider.name, "web_url": provider.web_origin, "skills": skills}
+
+
+@router.get("/hub/detail")
+async def hub_detail(slug: str, hub: str = "eduhub") -> dict[str, object]:
+    """Full metadata + SKILL.md body for one hub skill (browser detail view)."""
+    import asyncio
+
+    from deeptutor.services.skill.hub import ClawHubProvider, HubError, get_hub_provider
+
+    try:
+        provider = get_hub_provider(hub)
+    except HubError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if not isinstance(provider, ClawHubProvider):
+        raise HTTPException(status_code=400, detail=f"Hub `{hub}` does not support browsing.")
+    try:
+        detail = await asyncio.to_thread(provider.detail, slug)
+    except HubError as exc:
+        raise HTTPException(status_code=502, detail=str(exc))
+    detail["web_url"] = f"{provider.web_origin}/skills/{slug}"
+    return detail
+
+
+@router.get("/{name}")
+async def get_skill(name: str) -> dict[str, object]:
+    service = get_skill_service()
+    try:
+        return service.get_detail(name).to_dict()
+    except SkillNotFoundError:
+        # User scope doesn't have it. Fall through to admin-assigned lookup
+        # below, which returns 403 if the user has no grant for it.
+        pass
+    except InvalidSkillNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    user = get_current_user()
+    if user.is_admin:
+        # Admin scope already checked above; nothing else to look at.
+        raise HTTPException(status_code=404, detail=f"Skill not found: {name}")
+    if name not in assigned_skill_ids(user.id):
+        raise HTTPException(status_code=403, detail="Skill is not assigned to you")
+    detail = assigned_skill_detail(name)
+    if detail is None:
+        raise HTTPException(status_code=404, detail=f"Skill not found: {name}")
+    return detail
+
+
+@router.post("/create")
+async def create_skill(payload: CreateSkillRequest) -> dict[str, object]:
+    service = get_skill_service()
+    try:
+        info = service.create(
+            name=payload.name,
+            description=payload.description,
+            content=payload.content,
+            tags=list(payload.tags or []),
+        )
+        return info.to_dict()
+    except SkillExistsError:
+        raise HTTPException(status_code=409, detail=f"Skill already exists: {payload.name}")
+    except InvalidSkillNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except InvalidTagError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.post("/install")
+async def install_skill(payload: InstallSkillRequest) -> dict[str, object]:
+    """Import a hub skill (e.g. from EduHub) into the caller's own skill layer.
+
+    Lands the package in the same per-user dir that ``/create`` writes to, so
+    the imported skill shows up in this user's Skills list. The install gate
+    (``suspicious`` verdict abort, safe extraction, ``always`` stripping)
+    lives in :func:`deeptutor.services.skill.hub.install_from_hub`.
+    """
+    import asyncio
+
+    from deeptutor.services.skill.hub import HubError, install_from_hub
+
+    service = get_skill_service()
+    try:
+        outcome = await asyncio.to_thread(
+            install_from_hub,
+            payload.ref,
+            service=service,
+            rename_to=payload.name,
+            force=payload.force,
+            allow_unverified=payload.allow_unverified,
+        )
+    except SkillExistsError as exc:
+        raise HTTPException(status_code=409, detail=f"Skill already exists: {exc}")
+    except (SkillImportError, InvalidSkillNameError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except HubError as exc:
+        raise HTTPException(status_code=502, detail=str(exc))
+
+    return {
+        "skill": outcome.result.info.to_dict(),
+        "verdict": {"status": outcome.verdict.status, "detail": outcome.verdict.detail},
+        "version": outcome.ref.version,
+    }
+
+
+@router.put("/{name}")
+async def update_skill(name: str, payload: UpdateSkillRequest) -> dict[str, object]:
+    service = get_skill_service()
+    try:
+        info = service.update(
+            name,
+            description=payload.description,
+            content=payload.content,
+            rename_to=payload.rename_to,
+            tags=payload.tags,
+        )
+        return info.to_dict()
+    except SkillNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Skill not found: {name}")
+    except SkillReadOnlyError as exc:
+        raise HTTPException(status_code=403, detail=str(exc))
+    except SkillExistsError as exc:
+        raise HTTPException(status_code=409, detail=str(exc))
+    except InvalidSkillNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except InvalidTagError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.delete("/{name}")
+async def delete_skill(name: str) -> dict[str, str]:
+    service = get_skill_service()
+    try:
+        service.delete(name)
+        return {"status": "deleted", "name": name}
+    except SkillNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Skill not found: {name}")
+    except SkillReadOnlyError as exc:
+        raise HTTPException(status_code=403, detail=str(exc))
+    except InvalidSkillNameError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

deeptutor/api/routers/space_cli_apps.py

@@ -0,0 +1,222 @@
+"""
+CLI apps API
+============
+
+Mounted at ``/api/space/cli-apps``. Two audiences on one surface, split by
+method rather than by route prefix so the page has one thing to read:
+
+* **anyone signed in** — ``GET /apps`` (what is installed, and whether I may use
+  it), ``GET /catalog`` (what exists), ``PUT /apps/{id}/enabled`` (my own
+  preference among the apps I have been granted);
+* **administrators only** — ``POST /catalog/{id}/install`` and
+  ``DELETE /apps/{id}``.
+
+The admin routes are gated individually with ``Depends(require_admin)`` rather
+than by an all-router dependency, because installing is the privileged half and
+reading is not: installing runs a third-party ``setup.py`` in the application
+container, as the application user. That is the whole reason CLI apps are not
+self-service, and it is why an ordinary account's verb here is *enable*.
+
+Enabling is a preference, not a permission. The permission is
+``grant.cli_apps``, resolved server-side in ``cli_apps.provider``; an account can
+only switch off something it was granted, never switch on something it was not.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from deeptutor.api.routers.auth import require_admin
+from deeptutor.multi_user.paths import current_owner_id
+from deeptutor.multi_user.tool_access import allowed_cli_apps, exec_override
+from deeptutor.services.cli_apps import (
+    CliAppEntry,
+    catalog_pin,
+    category_counts,
+    get_entry,
+    search_catalog,
+)
+from deeptutor.services.cli_apps.models import TOOL_PREFIX
+from deeptutor.services.cli_apps.state import (
+    InstalledApp,
+    disabled_apps,
+    load_installed,
+    set_app_enabled,
+)
+from deeptutor.services.i18n import t
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+class EnabledPayload(BaseModel):
+    enabled: bool
+
+
+@router.get("/apps")
+async def list_apps() -> dict[str, Any]:
+    """Installed apps as *this* caller sees them."""
+    owner = current_owner_id()
+    installed = load_installed()
+    granted = allowed_cli_apps()
+    off = disabled_apps(owner)
+    exec_allowed = exec_override()
+
+    rows = [
+        _app_row(app, granted=granted, disabled=off)
+        for app in (installed[app_id] for app_id in sorted(installed))
+    ]
+    return {
+        "apps": rows,
+        # Why the list may be unusable even though it is not empty. Reported as a
+        # field rather than left for the reader to infer from every row being
+        # `granted: false`.
+        "access": {
+            "unrestricted": granted is None,
+            "exec_denied": exec_allowed is False,
+        },
+        "catalog_pin": catalog_pin(),
+    }
+
+
+@router.put("/apps/{app_id}/enabled")
+async def set_enabled(app_id: str, payload: EnabledPayload) -> dict[str, Any]:
+    """Switch one app on or off for the calling account.
+
+    Refused for an app the caller has not been granted: the preference file must
+    not become a way to record interest in something the grant denies, because a
+    later grant would then silently switch it on.
+    """
+    owner = current_owner_id()
+    installed = load_installed()
+    if app_id not in installed:
+        raise HTTPException(status_code=404, detail=t("cli_apps.not_installed", app=app_id))
+    granted = allowed_cli_apps()
+    if granted is not None and app_id not in granted:
+        raise HTTPException(
+            status_code=403,
+            detail={"code": "cli.not_granted", "message": t("cli_apps.entry_admin_only")},
+        )
+    set_app_enabled(owner, app_id, payload.enabled)
+    return await list_apps()
+
+
+@router.get("/catalog")
+async def get_catalog(
+    q: str = "",
+    category: str = "",
+    installable_only: bool = True,
+    cursor: str = "",
+    limit: int = 24,
+) -> dict[str, Any]:
+    """The store. Readable by anyone; installing is admin-only."""
+    installed = load_installed()
+    page = search_catalog(
+        q=q,
+        category=category,
+        installable_only=installable_only,
+        cursor=cursor,
+        limit=limit,
+    )
+    return {
+        "entries": [_catalog_row(entry, installed) for entry in page.entries],
+        "next_cursor": page.next_cursor,
+        "total": page.total,
+        "categories": category_counts(q=q, installable_only=installable_only),
+        "catalog_pin": catalog_pin(),
+    }
+
+
+@router.post("/catalog/{app_id}/install", dependencies=[Depends(require_admin)])
+async def install(app_id: str) -> dict[str, Any]:
+    """Install one app for the deployment. Administrator only."""
+    entry = get_entry(app_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=t("cli_apps.not_in_catalog", id=app_id))
+
+    from deeptutor.services.cli_apps.installer import install_app
+
+    outcome = await install_app(entry)
+    if not outcome.ok:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "code": outcome.code or "cli.install_failed",
+                "message": outcome.message,
+                # The install output is the only actionable thing about a failed
+                # install, so it travels with the refusal instead of only landing
+                # in a log file on the server.
+                "log": outcome.log,
+            },
+        )
+    state = await list_apps()
+    state["log"] = outcome.log
+    return state
+
+
+@router.delete("/apps/{app_id}", dependencies=[Depends(require_admin)])
+async def uninstall(app_id: str) -> dict[str, Any]:
+    """Remove one app from the deployment. Administrator only."""
+    from deeptutor.services.cli_apps.installer import uninstall_app
+
+    await uninstall_app(app_id)
+    return await list_apps()
+
+
+def _app_row(app: InstalledApp, *, granted: set[str] | None, disabled: set[str]) -> dict[str, Any]:
+    entry = get_entry(app.id)
+    is_granted = granted is None or app.id in granted
+    return {
+        "id": app.id,
+        "display_name": entry.display_name if entry else app.id,
+        "description": entry.description if entry else "",
+        "category": entry.category if entry else "",
+        "tool_name": f"{TOOL_PREFIX}{app.id}",
+        "entry_point": app.entry_point,
+        "runtime": app.runtime.value,
+        "installed_at": app.installed_at,
+        "version": app.version,
+        "pin": app.pin,
+        "trust": entry.trust.value if entry else "third-party",
+        "granted": is_granted,
+        # Only meaningful when granted; a denied app reports enabled=false so the
+        # UI never shows an "on" switch for something that cannot run.
+        "enabled": is_granted and app.id not in disabled,
+        # An app still installed but no longer in the snapshot: an admin can
+        # remove it, and the chat agent is not offered it.
+        "in_catalog": entry is not None,
+    }
+
+
+def _catalog_row(entry: CliAppEntry, installed: dict[str, InstalledApp]) -> dict[str, Any]:
+    return {
+        "id": entry.id,
+        "display_name": entry.display_name,
+        "description": entry.description,
+        "category": entry.category,
+        "origin": entry.origin,
+        "trust": entry.trust.value,
+        "requires": entry.requires,
+        "homepage": entry.homepage,
+        "source_url": entry.source_url,
+        "entry_point": entry.entry_point,
+        "runtime": entry.install.runtime.value,
+        "install_kind": entry.install.kind.value,
+        "install_target": entry.install.target,
+        "installable": entry.install.installable,
+        "pinned": entry.install.pinned,
+        # Present only when it is not installable, and written for a person: it
+        # is the difference between "we did not get to this one" and "its
+        # published install command is a shell script we will not run".
+        "unsupported_reason": entry.install.reason,
+        "install_notes": entry.install_notes,
+        "installed": entry.id in installed,
+    }
+
+
+__all__ = ["router"]