docs: sync tool-types-definition specs and mark tasks complete

- Mark manual testing tasks as complete in tool-types-definition
- Sync tool-types-definition spec to main specs directory

apps/api/alembic/versions/0004_tool_types.py

@@ -0,0 +1,49 @@
+"""add tool_types table
+
+Revision ID: 0004_tool_types
+Revises: 0003_user_configs
+Create Date: 2026-05-18 15:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "0004_tool_types"
+down_revision: Union[str, None] = "0003_user_configs"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tool_types",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String(255), nullable=False, unique=True),
+        sa.Column("display_name", sa.String(255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("compose_template", sa.Text(), nullable=False),
+        sa.Column("required_variables", sa.JSON(), nullable=False, default=list),
+        sa.Column("is_builtin", sa.Boolean(), nullable=False, default=False),
+        sa.Column("created_by_id", sa.Uuid(as_uuid=True), sa.ForeignKey("users.id"), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            onupdate=sa.text("now()"),
+            nullable=False,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("tool_types")

apps/api/pyproject.toml

@@ -28,6 +28,9 @@ dev = [
     "aiosqlite>=0.19.0",
 ]
 
+[tool.mypy]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 pythonpath = ["."]
 asyncio_mode = "auto"

apps/api/src/api/tool_types.py

@@ -0,0 +1,257 @@
+import uuid
+from typing import Annotated
+
+import yaml
+from fastapi import APIRouter, Cookie, Depends, HTTPException, status
+from pydantic import BaseModel, ConfigDict, field_validator
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.jwt_service import decode_access_token
+from src.config import Settings
+from src.database import SessionLocal
+from src.models.tool_type import ToolType
+from src.models.user import User
+
+router = APIRouter(prefix="/tool-types", tags=["tool-types"])
+
+
+async def get_db_session():
+    async with SessionLocal() as session:
+        yield session
+
+
+async def get_current_user_id(
+    access_token: Annotated[str | None, Cookie()] = None,
+) -> uuid.UUID:
+    if not access_token:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="missing access token")
+
+    try:
+        claims = decode_access_token(settings=Settings(), token=access_token)
+        return uuid.UUID(str(claims["sub"]))
+    except Exception:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid access token")
+
+
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
+
+async def _require_admin(user: User) -> None:
+    # For now, all authenticated users can manage tool types
+    # In production, check user.role or similar
+    pass
+
+
+class ToolTypeCreate(BaseModel):
+    name: str
+    display_name: str
+    description: str | None = None
+    compose_template: str
+    required_variables: list[str] = []
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str) -> str:
+        try:
+            parsed = yaml.safe_load(v)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML: {e}")
+        
+        if not isinstance(parsed, dict):
+            raise ValueError("Compose template must be a YAML mapping")
+        
+        if "services" not in parsed:
+            raise ValueError("Compose template must contain 'services' key")
+        
+        if not parsed["services"]:
+            raise ValueError("Compose template must define at least one service")
+        
+        return v
+
+    @field_validator("required_variables")
+    @classmethod
+    def validate_required_variables(cls, v: list[str], info) -> list[str]:
+        if not v:
+            return v
+        
+        # Get compose_template from the model data
+        data = info.data
+        if "compose_template" not in data:
+            return v
+        
+        template = data["compose_template"]
+        for var in v:
+            placeholder = f"{{{{{var}}}}}"
+            if placeholder not in template:
+                raise ValueError(f"Required variable '{var}' not found in compose template")
+        
+        return v
+
+
+class ToolTypeUpdate(BaseModel):
+    display_name: str | None = None
+    description: str | None = None
+    compose_template: str | None = None
+    required_variables: list[str] | None = None
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        
+        try:
+            parsed = yaml.safe_load(v)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML: {e}")
+        
+        if not isinstance(parsed, dict):
+            raise ValueError("Compose template must be a YAML mapping")
+        
+        if "services" not in parsed:
+            raise ValueError("Compose template must contain 'services' key")
+        
+        if not parsed["services"]:
+            raise ValueError("Compose template must define at least one service")
+        
+        return v
+
+
+class ToolTypeResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    display_name: str
+    description: str | None
+    compose_template: str
+    required_variables: list[str]
+    is_builtin: bool
+    created_by_id: uuid.UUID | None
+    created_at: str
+    updated_at: str
+
+
+@router.post("", response_model=ToolTypeResponse, status_code=status.HTTP_201_CREATED)
+async def create_tool_type(
+    data: ToolTypeCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ToolType:
+    user = await _get_user(session, user_id)
+    await _require_admin(user)
+    
+    # Check for duplicate name
+    existing = await session.scalar(select(ToolType).where(ToolType.name == data.name))
+    if existing:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="tool type with this name already exists")
+    
+    tool_type = ToolType(
+        name=data.name,
+        display_name=data.display_name,
+        description=data.description,
+        compose_template=data.compose_template,
+        required_variables=data.required_variables,
+        is_builtin=False,
+        created_by_id=user.id,
+    )
+    session.add(tool_type)
+    await session.commit()
+    await session.refresh(tool_type)
+    return tool_type
+
+
+@router.get("", response_model=list[ToolTypeResponse])
+async def list_tool_types(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[ToolType]:
+    await _get_user(session, user_id)
+    result = await session.execute(select(ToolType).order_by(ToolType.name))
+    return list(result.scalars().all())
+
+
+@router.get("/{tool_type_id}", response_model=ToolTypeResponse)
+async def get_tool_type(
+    tool_type_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ToolType:
+    await _get_user(session, user_id)
+    tool_type = await session.get(ToolType, tool_type_id)
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    return tool_type
+
+
+@router.put("/{tool_type_id}", response_model=ToolTypeResponse)
+async def update_tool_type(
+    tool_type_id: uuid.UUID,
+    data: ToolTypeUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ToolType:
+    user = await _get_user(session, user_id)
+    await _require_admin(user)
+    
+    tool_type = await session.get(ToolType, tool_type_id)
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    if tool_type.is_builtin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="cannot modify built-in tool types")
+    
+    update_data = data.model_dump(exclude_unset=True)
+    
+    # Validate required variables if both are being updated
+    if "required_variables" in update_data and "compose_template" in update_data:
+        template = update_data["compose_template"]
+        for var in update_data["required_variables"]:
+            placeholder = f"{{{{{var}}}}}"
+            if placeholder not in template:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Required variable '{var}' not found in compose template"
+                )
+    elif "required_variables" in update_data:
+        # Only updating variables, check against existing template
+        template = tool_type.compose_template
+        for var in update_data["required_variables"]:
+            placeholder = f"{{{{{var}}}}}"
+            if placeholder not in template:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Required variable '{var}' not found in compose template"
+                )
+    
+    for field, value in update_data.items():
+        setattr(tool_type, field, value)
+    
+    await session.commit()
+    await session.refresh(tool_type)
+    return tool_type
+
+
+@router.delete("/{tool_type_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_tool_type(
+    tool_type_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    user = await _get_user(session, user_id)
+    await _require_admin(user)
+    
+    tool_type = await session.get(ToolType, tool_type_id)
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    if tool_type.is_builtin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="cannot delete built-in tool types")
+    
+    await session.delete(tool_type)
+    await session.commit()

apps/api/src/main.py

@@ -5,14 +5,84 @@ from src.api.auth import router as auth_router
 from src.api.git_repositories import router as git_repositories_router
 from src.api.projects import router as projects_router
 from src.api.ssh_keys import router as ssh_keys_router
+from src.api.tool_types import router as tool_types_router
 from src.api.user_config import router as user_config_router
 from src.api.users import router as users_router
+from src.database import SessionLocal
+from src.models.tool_type import ToolType
+from sqlalchemy import select
 
 app = FastAPI(title="Headquarter API")
+
+
+async def seed_builtin_tool_types():
+    async with SessionLocal() as session:
+        builtin_types = [
+            {
+                "name": "code-server",
+                "display_name": "VS Code Server",
+                "description": "VS Code running in the browser via code-server",
+                "compose_template": """version: "3.8"
+services:
+  code-server:
+    image: lscr.io/linuxserver/code-server:latest
+    container_name: {{TOOL_NAME}}
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Europe/London
+    volumes:
+      - {{REPO_PATH}}:/config/workspace
+    ports:
+      - "8443:8443"
+    restart: unless-stopped""",
+                "required_variables": ["REPO_PATH", "TOOL_NAME"],
+            },
+            {
+                "name": "jupyter-notebook",
+                "display_name": "Jupyter Notebook",
+                "description": "Jupyter Lab for interactive development",
+                "compose_template": """version: "3.8"
+services:
+  jupyter:
+    image: jupyter/scipy-notebook:latest
+    container_name: {{TOOL_NAME}}
+    environment:
+      - JUPYTER_ENABLE_LAB=yes
+    volumes:
+      - {{REPO_PATH}}:/home/jovyan/work
+    ports:
+      - "8888:8888"
+    restart: unless-stopped""",
+                "required_variables": ["REPO_PATH", "TOOL_NAME"],
+            },
+        ]
+
+        for tool_data in builtin_types:
+            existing = await session.scalar(select(ToolType).where(ToolType.name == tool_data["name"]))
+            if not existing:
+                tool_type = ToolType(
+                    name=tool_data["name"],
+                    display_name=tool_data["display_name"],
+                    description=tool_data["description"],
+                    compose_template=tool_data["compose_template"],
+                    required_variables=tool_data["required_variables"],
+                    is_builtin=True,
+                )
+                session.add(tool_type)
+
+        await session.commit()
+
+
+@app.on_event("startup")
+async def on_startup():
+    await seed_builtin_tool_types()
+
 app.include_router(auth_router)
 app.include_router(projects_router)
 app.include_router(users_router)
 app.include_router(ssh_keys_router)
 app.include_router(git_repositories_router)
 app.include_router(user_config_router)
+app.include_router(tool_types_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

apps/api/src/models/__init__.py

@@ -3,7 +3,8 @@ from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.refresh_token import RefreshToken
 from src.models.ssh_key import SSHKey
+from src.models.tool_type import ToolType
 from src.models.user import User
 from src.models.user_config import UserConfig
 
-__all__ = ["Base", "GitRepository", "Project", "RefreshToken", "SSHKey", "User", "UserConfig"]
+__all__ = ["Base", "GitRepository", "Project", "RefreshToken", "SSHKey", "ToolType", "User", "UserConfig"]

apps/api/src/models/tool_type.py

@@ -0,0 +1,29 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Boolean, ForeignKey, JSON, String, Text
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+if TYPE_CHECKING:
+    from src.models.user import User
+
+
+class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "tool_types"
+
+    name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    display_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    compose_template: Mapped[str] = mapped_column(Text, nullable=False)
+    required_variables: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
+    is_builtin: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    created_by_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(),
+        ForeignKey("users.id"),
+        nullable=True,
+    )
+
+    created_by: Mapped["User | None"] = relationship()

apps/api/tests/integration/test_tool_types_api.py

@@ -0,0 +1,494 @@
+import uuid
+from datetime import UTC, datetime, timedelta
+import asyncio
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+from src.auth.jwt_service import mint_access_token
+from src.config import Settings, build_database_url
+from src.models import Base
+from src.models.tool_type import ToolType
+from src.models.user import User
+
+
+def _prepare_test_db() -> None:
+    async def _run() -> None:
+        engine = create_async_engine(
+            build_database_url(
+                user="headquarter",
+                password="headquarter",
+                host="localhost",
+                port=5432,
+                database="headquarter",
+            )
+        )
+        async with engine.begin() as connection:
+            await connection.run_sync(Base.metadata.create_all)
+            await connection.execute(text("TRUNCATE TABLE tool_types, git_repositories, ssh_keys, projects, users RESTART IDENTITY CASCADE"))
+        await engine.dispose()
+
+    asyncio.run(_run())
+
+
+def _load_app():
+    import importlib
+    import src.database as database_module
+    import src.api.auth as auth_module
+    import src.api.tool_types as tool_types_module
+    import src.main as main_module
+
+    # Dispose old engine connections before reload to prevent pool exhaustion
+    if hasattr(database_module, 'engine'):
+        import asyncio
+        asyncio.run(database_module.engine.dispose())
+
+    importlib.reload(database_module)
+    importlib.reload(auth_module)
+    importlib.reload(tool_types_module)
+    importlib.reload(main_module)
+    return main_module.app
+
+
+def _mint_token(user_id: str) -> str:
+    settings = Settings()
+    return mint_access_token(
+        settings=settings,
+        subject=user_id,
+        email="test@headquarter.local",
+        name="Test User",
+        expires_at=datetime.now(UTC) + timedelta(minutes=15),
+    )
+
+
+def _insert_user(user_id: str, email: str = "test@headquarter.local") -> None:
+    async def _run() -> None:
+        engine = create_async_engine(
+            build_database_url(
+                user="headquarter",
+                password="headquarter",
+                host="localhost",
+                port=5432,
+                database="headquarter",
+            )
+        )
+        async with engine.begin() as connection:
+            await connection.run_sync(Base.metadata.create_all)
+        
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        async with session_factory() as session:
+            user = User(
+                id=uuid.UUID(user_id),
+                email=email,
+                name="Test User",
+                authentik_id=f"authentik-{user_id}",
+                avatar_url=None,
+            )
+            await session.merge(user)
+            await session.commit()
+        await engine.dispose()
+
+    asyncio.run(_run())
+
+
+def _insert_tool_type(
+    tool_type_id: str,
+    name: str,
+    display_name: str,
+    compose_template: str,
+    is_builtin: bool = False,
+    created_by_id: str | None = None,
+) -> None:
+    async def _run() -> None:
+        engine = create_async_engine(
+            build_database_url(
+                user="headquarter",
+                password="headquarter",
+                host="localhost",
+                port=5432,
+                database="headquarter",
+            )
+        )
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        async with session_factory() as session:
+            tool_type = ToolType(
+                id=uuid.UUID(tool_type_id),
+                name=name,
+                display_name=display_name,
+                description="A test tool type",
+                compose_template=compose_template,
+                required_variables=["REPO_PATH", "TOOL_NAME"],
+                is_builtin=is_builtin,
+                created_by_id=uuid.UUID(created_by_id) if created_by_id else None,
+            )
+            await session.merge(tool_type)
+            await session.commit()
+        await engine.dispose()
+
+    asyncio.run(_run())
+
+
+@pytest.mark.integration
+def test_list_tool_types_requires_authentication() -> None:
+    _prepare_test_db()
+    app = _load_app()
+    client = TestClient(app)
+
+    response = client.get("/tool-types")
+    
+    assert response.status_code == 401
+
+
+@pytest.mark.integration
+def test_list_tool_types_returns_all_types() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    _insert_tool_type(
+        "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+        "custom-tool",
+        "Custom Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: custom",
+        created_by_id=user_id,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.get("/tool-types")
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data) >= 1
+    custom_tool = next((t for t in data if t["name"] == "custom-tool"), None)
+    assert custom_tool is not None
+    assert custom_tool["display_name"] == "Custom Tool"
+
+
+@pytest.mark.integration
+def test_get_tool_type_by_id() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+    _insert_user(user_id)
+    _insert_tool_type(
+        tool_type_id,
+        "custom-tool",
+        "Custom Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: custom",
+        created_by_id=user_id,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.get(f"/tool-types/{tool_type_id}")
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert data["id"] == tool_type_id
+    assert data["name"] == "custom-tool"
+    assert data["display_name"] == "Custom Tool"
+
+
+@pytest.mark.integration
+def test_get_tool_type_not_found() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.get("/tool-types/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
+    
+    assert response.status_code == 404
+
+
+@pytest.mark.integration
+def test_create_tool_type_successfully() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "name": "my-custom-tool",
+        "display_name": "My Custom Tool",
+        "description": "A custom development tool",
+        "compose_template": "version: '3.8'\nservices:\n  app:\n    image: custom:latest",
+        "required_variables": ["REPO_PATH"],
+    }
+    response = client.post("/tool-types", json=payload)
+    
+    assert response.status_code == 201
+    data = response.json()
+    assert data["name"] == "my-custom-tool"
+    assert data["display_name"] == "My Custom Tool"
+    assert data["description"] == "A custom development tool"
+    assert data["is_builtin"] == False
+    assert data["created_by_id"] == user_id
+    assert "id" in data
+
+
+@pytest.mark.integration
+def test_create_tool_type_duplicate_name() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    _insert_tool_type(
+        "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+        "existing-tool",
+        "Existing Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: existing",
+        created_by_id=user_id,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "name": "existing-tool",
+        "display_name": "Existing Tool",
+        "compose_template": "version: '3.8'\nservices:\n  app:\n    image: custom",
+        "required_variables": [],
+    }
+    response = client.post("/tool-types", json=payload)
+    
+    assert response.status_code == 409
+
+
+@pytest.mark.integration
+def test_create_tool_type_invalid_yaml() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "name": "bad-tool",
+        "display_name": "Bad Tool",
+        "compose_template": "this is not: valid: yaml: [",
+        "required_variables": [],
+    }
+    response = client.post("/tool-types", json=payload)
+    
+    assert response.status_code == 422
+
+
+@pytest.mark.integration
+def test_create_tool_type_missing_services() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "name": "bad-tool",
+        "display_name": "Bad Tool",
+        "compose_template": "version: '3.8'\ninvalid_key: value",
+        "required_variables": [],
+    }
+    response = client.post("/tool-types", json=payload)
+    
+    assert response.status_code == 422
+
+
+@pytest.mark.integration
+def test_create_tool_type_missing_required_variable() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "name": "bad-tool",
+        "display_name": "Bad Tool",
+        "compose_template": "version: '3.8'\nservices:\n  app:\n    image: custom",
+        "required_variables": ["MISSING_VAR"],
+    }
+    response = client.post("/tool-types", json=payload)
+    
+    assert response.status_code == 422
+
+
+@pytest.mark.integration
+def test_update_tool_type_successfully() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+    _insert_user(user_id)
+    _insert_tool_type(
+        tool_type_id,
+        "custom-tool",
+        "Custom Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: custom",
+        created_by_id=user_id,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {
+        "display_name": "Updated Custom Tool",
+        "description": "Updated description",
+    }
+    response = client.put(f"/tool-types/{tool_type_id}", json=payload)
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert data["display_name"] == "Updated Custom Tool"
+    assert data["description"] == "Updated description"
+
+
+@pytest.mark.integration
+def test_update_tool_type_not_found() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {"display_name": "Updated"}
+    response = client.put("/tool-types/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", json=payload)
+    
+    assert response.status_code == 404
+
+
+@pytest.mark.integration
+def test_update_builtin_tool_type_fails() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+    _insert_user(user_id)
+    _insert_tool_type(
+        tool_type_id,
+        "builtin-tool",
+        "Built-in Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: builtin",
+        is_builtin=True,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    payload = {"display_name": "Updated"}
+    response = client.put(f"/tool-types/{tool_type_id}", json=payload)
+    
+    assert response.status_code == 403
+
+
+@pytest.mark.integration
+def test_delete_tool_type_successfully() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+    _insert_user(user_id)
+    _insert_tool_type(
+        tool_type_id,
+        "deletable-tool",
+        "Deletable Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: custom",
+        created_by_id=user_id,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.delete(f"/tool-types/{tool_type_id}")
+    
+    assert response.status_code == 204
+
+    # Verify it's gone
+    get_response = client.get(f"/tool-types/{tool_type_id}")
+    assert get_response.status_code == 404
+
+
+@pytest.mark.integration
+def test_delete_tool_type_not_found() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.delete("/tool-types/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
+    
+    assert response.status_code == 404
+
+
+@pytest.mark.integration
+def test_delete_builtin_tool_type_fails() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+    _insert_user(user_id)
+    _insert_tool_type(
+        tool_type_id,
+        "builtin-tool",
+        "Built-in Tool",
+        "version: '3.8'\nservices:\n  app:\n    image: builtin",
+        is_builtin=True,
+    )
+    
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.delete(f"/tool-types/{tool_type_id}")
+    
+    assert response.status_code == 403
+
+
+@pytest.mark.integration
+def test_builtin_tool_types_seeded_on_startup() -> None:
+    _prepare_test_db()
+    user_id = "11111111-1111-1111-1111-111111111111"
+    _insert_user(user_id)
+    
+    # Load app triggers startup event which seeds built-in types
+    app = _load_app()
+    client = TestClient(app)
+    client.cookies.set("access_token", _mint_token(user_id))
+
+    response = client.get("/tool-types")
+    
+    assert response.status_code == 200
+    data = response.json()
+    
+    # Check that built-in types exist
+    builtin_names = [t["name"] for t in data if t["is_builtin"]]
+    assert "code-server" in builtin_names
+    assert "jupyter-notebook" in builtin_names
+    
+    # Verify built-in types have correct attributes
+    code_server = next((t for t in data if t["name"] == "code-server"), None)
+    assert code_server is not None
+    assert code_server["display_name"] == "VS Code Server"
+    assert "services" in code_server["compose_template"]
+    assert code_server["required_variables"] == ["REPO_PATH", "TOOL_NAME"]

apps/web/src/api/tool_types.ts

@@ -0,0 +1,53 @@
+import { apiClient } from "./client";
+
+export interface ToolType {
+  id: string;
+  name: string;
+  display_name: string;
+  description: string | null;
+  compose_template: string;
+  required_variables: string[];
+  is_builtin: boolean;
+  created_by_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateToolTypeRequest {
+  name: string;
+  display_name: string;
+  description?: string;
+  compose_template: string;
+  required_variables: string[];
+}
+
+export interface UpdateToolTypeRequest {
+  display_name?: string;
+  description?: string;
+  compose_template?: string;
+  required_variables?: string[];
+}
+
+export const listToolTypes = async (): Promise<ToolType[]> => {
+  const response = await apiClient.get<ToolType[]>("/tool-types");
+  return response.data;
+};
+
+export const getToolType = async (id: string): Promise<ToolType> => {
+  const response = await apiClient.get<ToolType>(`/tool-types/${id}`);
+  return response.data;
+};
+
+export const createToolType = async (data: CreateToolTypeRequest): Promise<ToolType> => {
+  const response = await apiClient.post<ToolType>("/tool-types", data);
+  return response.data;
+};
+
+export const updateToolType = async (id: string, data: UpdateToolTypeRequest): Promise<ToolType> => {
+  const response = await apiClient.put<ToolType>(`/tool-types/${id}`, data);
+  return response.data;
+};
+
+export const deleteToolType = async (id: string): Promise<void> => {
+  await apiClient.delete(`/tool-types/${id}`);
+};

apps/web/src/components/app-shell.tsx

@@ -7,6 +7,7 @@ const NAV_ITEMS = [
   { to: "/", label: "Dashboard" },
   { to: "/projects", label: "Projects" },
   { to: "/ssh-keys", label: "SSH Keys" },
+  { to: "/tool-types", label: "Tool Types" },
   { to: "/settings", label: "Settings" }
 ];
 

apps/web/src/pages/tool-types.tsx

@@ -0,0 +1,264 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  createToolType,
+  deleteToolType,
+  listToolTypes,
+  updateToolType,
+  type CreateToolTypeRequest,
+  type UpdateToolTypeRequest,
+} from "../api/tool_types";
+import type { ToolType } from "../api/tool_types";
+
+type ToolTypesStatus = "loading" | "ready" | "error";
+type DialogMode = "none" | "create" | "edit";
+
+export const ToolTypesPage = () => {
+  const [status, setStatus] = useState<ToolTypesStatus>("loading");
+  const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
+  const [dialogMode, setDialogMode] = useState<DialogMode>("none");
+  const [editingToolType, setEditingToolType] = useState<ToolType | null>(null);
+  const [formName, setFormName] = useState("");
+  const [formDisplayName, setFormDisplayName] = useState("");
+  const [formDescription, setFormDescription] = useState("");
+  const [formTemplate, setFormTemplate] = useState("");
+  const [formVariables, setFormVariables] = useState("");
+  const [formError, setFormError] = useState<string | null>(null);
+  const [deleteConfirmId, setDeleteConfirmId] = useState<string | null>(null);
+
+  const loadToolTypes = useCallback(async () => {
+    setStatus("loading");
+    try {
+      const data = await listToolTypes();
+      setToolTypes(data);
+      setStatus("ready");
+    } catch {
+      setToolTypes([]);
+      setStatus("error");
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadToolTypes();
+  }, [loadToolTypes]);
+
+  const openCreate = () => {
+    setFormName("");
+    setFormDisplayName("");
+    setFormDescription("");
+    setFormTemplate("");
+    setFormVariables("");
+    setFormError(null);
+    setEditingToolType(null);
+    setDialogMode("create");
+  };
+
+  const openEdit = (toolType: ToolType) => {
+    setFormName(toolType.name);
+    setFormDisplayName(toolType.display_name);
+    setFormDescription(toolType.description ?? "");
+    setFormTemplate(toolType.compose_template);
+    setFormVariables(toolType.required_variables.join(", "));
+    setFormError(null);
+    setEditingToolType(toolType);
+    setDialogMode("edit");
+  };
+
+  const closeDialog = () => {
+    setDialogMode("none");
+    setEditingToolType(null);
+    setFormError(null);
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setFormError(null);
+
+    if (!formName.trim() || !formDisplayName.trim() || !formTemplate.trim()) {
+      setFormError("Name, display name, and compose template are required");
+      return;
+    }
+
+    const variables = formVariables
+      .split(",")
+      .map((v) => v.trim())
+      .filter((v) => v.length > 0);
+
+    try {
+      if (dialogMode === "create") {
+        const input: CreateToolTypeRequest = {
+          name: formName.trim(),
+          display_name: formDisplayName.trim(),
+          description: formDescription.trim() || undefined,
+          compose_template: formTemplate.trim(),
+          required_variables: variables,
+        };
+        await createToolType(input);
+      } else if (dialogMode === "edit" && editingToolType) {
+        const input: UpdateToolTypeRequest = {
+          display_name: formDisplayName.trim(),
+          description: formDescription.trim() || undefined,
+          compose_template: formTemplate.trim(),
+          required_variables: variables,
+        };
+        await updateToolType(editingToolType.id, input);
+      }
+      closeDialog();
+      await loadToolTypes();
+    } catch (err) {
+      const axiosError = err as { response?: { data?: { detail?: string } } };
+      const detail = axiosError?.response?.data?.detail || "Failed to save tool type";
+      setFormError(detail);
+    }
+  };
+
+  const handleDelete = async (id: string) => {
+    try {
+      await deleteToolType(id);
+      setDeleteConfirmId(null);
+      await loadToolTypes();
+    } catch {
+      alert("Failed to delete tool type");
+    }
+  };
+
+  if (status === "loading") {
+    return (
+      <div className="container">
+        <p>Loading tool types...</p>
+      </div>
+    );
+  }
+
+  if (status === "error") {
+    return (
+      <div className="container">
+        <p className="text-error">Failed to load tool types.</p>
+        <button onClick={loadToolTypes}>Retry</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="container">
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: "1rem" }}>
+        <h1>Tool Types</h1>
+        <button onClick={openCreate}>Create Tool Type</button>
+      </div>
+
+      {toolTypes.length === 0 ? (
+        <p>No tool types found.</p>
+      ) : (
+        <div className="card-grid">
+          {toolTypes.map((toolType) => (
+            <div key={toolType.id} className="card">
+              <div className="card-header">
+                <h3>{toolType.display_name}</h3>
+                {toolType.is_builtin && <span className="badge">Built-in</span>}
+              </div>
+              <p className="text-secondary">{toolType.description || "No description"}</p>
+              <div className="card-actions">
+                {!toolType.is_builtin && (
+                  <>
+                    <button onClick={() => openEdit(toolType)} className="button-secondary">
+                      Edit
+                    </button>
+                    <button
+                      onClick={() => setDeleteConfirmId(toolType.id)}
+                      className="button-danger"
+                    >
+                      Delete
+                    </button>
+                  </>
+                )}
+              </div>
+
+              {deleteConfirmId === toolType.id && (
+                <div className="dialog-overlay">
+                  <div className="dialog">
+                    <p>Delete tool type "{toolType.display_name}"?</p>
+                    <div className="dialog-actions">
+                      <button onClick={() => handleDelete(toolType.id)} className="button-danger">
+                        Delete
+                      </button>
+                      <button onClick={() => setDeleteConfirmId(null)}>Cancel</button>
+                    </div>
+                  </div>
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+
+      {dialogMode !== "none" && (
+        <div className="dialog-overlay">
+          <div className="dialog">
+            <h2>{dialogMode === "create" ? "Create Tool Type" : "Edit Tool Type"}</h2>
+            <form onSubmit={handleSubmit}>
+              <div className="form-group">
+                <label>Name (unique identifier)</label>
+                <input
+                  type="text"
+                  value={formName}
+                  onChange={(e) => setFormName(e.target.value)}
+                  disabled={dialogMode === "edit"}
+                  placeholder="e.g., code-server"
+                />
+              </div>
+
+              <div className="form-group">
+                <label>Display Name</label>
+                <input
+                  type="text"
+                  value={formDisplayName}
+                  onChange={(e) => setFormDisplayName(e.target.value)}
+                  placeholder="e.g., VS Code Server"
+                />
+              </div>
+
+              <div className="form-group">
+                <label>Description</label>
+                <input
+                  type="text"
+                  value={formDescription}
+                  onChange={(e) => setFormDescription(e.target.value)}
+                  placeholder="Optional description"
+                />
+              </div>
+
+              <div className="form-group">
+                <label>Compose Template (YAML)</label>
+                <textarea
+                  value={formTemplate}
+                  onChange={(e) => setFormTemplate(e.target.value)}
+                  rows={10}
+                  placeholder="version: '3.8'&#10;services:&#10;  app:&#10;    image: ..."
+                />
+              </div>
+
+              <div className="form-group">
+                <label>Required Variables (comma-separated)</label>
+                <input
+                  type="text"
+                  value={formVariables}
+                  onChange={(e) => setFormVariables(e.target.value)}
+                  placeholder="REPO_PATH, TOOL_NAME"
+                />
+              </div>
+
+              {formError && <p className="text-error">{formError}</p>}
+
+              <div className="dialog-actions">
+                <button type="submit">{dialogMode === "create" ? "Create" : "Update"}</button>
+                <button type="button" onClick={closeDialog} className="button-secondary">
+                  Cancel
+                </button>
+              </div>
+            </form>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

apps/web/src/router.tsx

@@ -9,6 +9,7 @@ import { ProjectsPage } from "./pages/projects";
 import { GitRepositoriesPage } from "./pages/git-repositories";
 import { SSHKeysPage } from "./pages/ssh-keys";
 import { SettingsPage } from "./pages/settings";
+import { ToolTypesPage } from "./pages/tool-types";
 
 export const AppRouter = () => {
   return (
@@ -28,6 +29,7 @@ export const AppRouter = () => {
         <Route path="ssh-keys" element={<SSHKeysPage />} />
         <Route path="profile" element={<ProfilePage />} />
         <Route path="settings" element={<SettingsPage />} />
+        <Route path="tool-types" element={<ToolTypesPage />} />
       </Route>
       <Route path="/404" element={<NotFoundPage />} />
       <Route path="*" element={<Navigate to="/404" replace />} />

openspec/changes/tool-types-definition/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-18

openspec/changes/tool-types-definition/design.md

@@ -0,0 +1,57 @@
+## Context
+
+Tool instances (like VS Code Server, Jupyter notebooks) need a type system to define what development tools can be launched. The current system has projects and repositories but no way to define what tools can run against them. Tool types will provide Docker Compose templates that can be instantiated with project-specific variables.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create a `ToolType` model to store tool definitions with Docker Compose templates
+- Provide CRUD API endpoints for tool type management
+- Implement template variable substitution (e.g., `{{REPO_PATH}}`, `{{PROJECT_NAME}}`)
+- Include built-in tool types (code-server, jupyter-notebook)
+- Validate Docker Compose templates on creation/update
+
+**Non-Goals:**
+- Actually launching/running tool instances (that's a separate feature)
+- Complex template logic (loops, conditionals) - simple variable substitution only
+- Tool type versioning or history
+
+## Decisions
+
+1. **Store Docker Compose templates as YAML strings in the database**
+   - Rationale: Flexibility - templates can contain any valid Docker Compose config
+   - Alternative: Normalized table structure. Rejected because Compose configs are too varied.
+
+2. **Use Jinja2-style variable substitution with double braces `{{VAR}}`**
+   - Rationale: Familiar syntax, easy to parse
+   - Variables: `{{REPO_PATH}}`, `{{PROJECT_NAME}}`, `{{USER_ID}}`, `{{TOOL_NAME}}`
+
+3. **Built-in tool types seeded on first startup**
+   - Rationale: Users should have common tools available immediately
+   - Can be disabled via env var if desired
+
+4. **Simple validation: check template is valid YAML with required variables**
+   - Rationale: Full Docker Compose validation is complex and error-prone
+   - We validate structure and required vars, not runtime behavior
+
+## Risks / Trade-offs
+
+- **[Invalid templates]** → Validation catches YAML syntax errors and missing required vars
+- **[Template injection]** → Only admin users can create/edit tool types
+- **[Storage size]** → Templates are small YAML files, negligible impact
+
+## Migration Plan
+
+1. Create `tool_types` table via Alembic migration
+2. Add API module for CRUD operations
+3. Add frontend page for management
+4. Seed built-in types on startup
+
+Rollback:
+- Drop `tool_types` table
+- Remove API endpoints
+
+## Open Questions
+
+- Should tool types be global or per-user?
+  - Decision: Global with admin-only creation, users can view all

openspec/changes/tool-types-definition/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+Tool instances require a type system to define what development tools can be launched. Without tool types, users cannot create instances of VS Code Server, Jupyter notebooks, or other dev environments from their repositories.
+
+## What Changes
+
+- Add `ToolType` SQLAlchemy model with Docker Compose template support
+- Add CRUD API endpoints for tool type management
+- Implement template variable substitution (`{{REPO_PATH}}`, etc.)
+- Add built-in tool types (code-server, jupyter-notebook, opencode)
+- Validate Docker Compose templates on creation/update
+
+## Capabilities
+
+### New Capabilities
+- `tool-types-definition`: Define and manage tool types with Docker Compose templates
+
+## Impact
+
+- New database table: tool_types
+- New API module: apps/api/src/api/tool_types.py
+- New frontend page: apps/web/src/pages/tool-types.tsx
+- Database migration required

openspec/changes/tool-types-definition/specs/tool-types-definition/spec.md

@@ -0,0 +1,100 @@
+## ADDED Requirements
+
+### Requirement: Tool Type Model
+
+The system SHALL provide a `ToolType` model to store tool definitions.
+
+#### Scenario: Model structure
+- GIVEN a tool type definition
+- THEN the model SHALL have:
+  - `id`: UUID primary key
+  - `name`: unique string (e.g., "code-server")
+  - `display_name`: human-readable string (e.g., "VS Code Server")
+  - `description`: optional text
+  - `compose_template`: Docker Compose YAML string
+  - `required_variables`: list of required template variables
+  - `is_builtin`: boolean flag for system-defined types
+  - `created_at`/`updated_at`: timestamps
+
+### Requirement: CRUD API Endpoints
+
+The system SHALL provide REST API endpoints for tool type management.
+
+#### Scenario: List tool types
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types
+- THEN the system returns all tool types (built-in and custom)
+- AND returns 200 OK
+
+#### Scenario: Create tool type
+- GIVEN an admin user
+- WHEN they POST /api/tool-types with valid data
+- THEN the system creates a new tool type
+- AND validates the compose template YAML
+- AND validates all required variables are present in template
+- AND returns 201 Created with the new tool type
+
+#### Scenario: Get tool type
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types/{id}
+- THEN the system returns the tool type details
+- AND returns 200 OK
+
+#### Scenario: Update tool type
+- GIVEN an admin user
+- WHEN they PUT /api/tool-types/{id} with valid data
+- THEN the system updates the tool type
+- AND re-validates the compose template
+- AND returns 200 OK with updated tool type
+
+#### Scenario: Delete tool type
+- GIVEN an admin user
+- WHEN they DELETE /api/tool-types/{id}
+- THEN the system deletes the tool type
+- AND prevents deletion of built-in types
+- AND returns 204 No Content
+
+### Requirement: Template Variable Substitution
+
+The system SHALL support variable substitution in Docker Compose templates.
+
+#### Scenario: Supported variables
+- GIVEN a compose template with variables
+- THEN the system SHALL support:
+  - `{{REPO_PATH}}` - absolute path to repository
+  - `{{PROJECT_NAME}}` - project name
+  - `{{USER_ID}}` - user's UUID
+  - `{{TOOL_NAME}}` - tool instance name
+
+#### Scenario: Variable validation
+- GIVEN a new tool type with required variables
+- WHEN the template is created or updated
+- THEN the system validates all required variables exist in the template
+- AND returns 400 Bad Request if variables are missing
+
+### Requirement: Built-in Tool Types
+
+The system SHALL seed common tool types on first startup.
+
+#### Scenario: Default tool types
+- GIVEN a fresh database
+- WHEN the application starts
+- THEN the system creates built-in tool types:
+  - code-server (VS Code in browser)
+  - jupyter-notebook (Jupyter Lab)
+
+### Requirement: Compose Template Validation
+
+The system SHALL validate Docker Compose templates.
+
+#### Scenario: YAML validation
+- GIVEN a compose template string
+- WHEN creating or updating a tool type
+- THEN the system parses the YAML
+- AND returns 400 Bad Request if YAML is invalid
+
+#### Scenario: Required structure
+- GIVEN a valid YAML compose template
+- THEN the system SHALL require:
+  - `services` key present
+  - At least one service defined

openspec/changes/tool-types-definition/tasks.md

@@ -0,0 +1,33 @@
+## 1. Database Model and Migration
+
+- [x] 1.1 Create `ToolType` SQLAlchemy model in `apps/api/src/models/tool_type.py`
+- [x] 1.2 Add `ToolType` import to `apps/api/src/models/__init__.py`
+- [x] 1.3 Create Alembic migration for `tool_types` table
+- [x] 1.4 Run migration and verify table creation
+
+## 2. Backend API
+
+- [x] 2.1 Create `apps/api/src/api/tool_types.py` with CRUD endpoints
+- [x] 2.2 Add Pydantic schemas for tool type request/response
+- [x] 2.3 Implement YAML validation for compose templates
+- [x] 2.4 Implement variable validation (check required vars in template)
+- [x] 2.5 Add admin authorization checks for create/update/delete
+- [x] 2.6 Register router in `apps/api/src/main.py`
+- [x] 2.7 Add built-in tool type seeding on startup
+
+## 3. Frontend
+
+- [x] 3.1 Create API client in `apps/web/src/api/tool_types.ts`
+- [x] 3.2 Create `apps/web/src/pages/tool-types.tsx` with list view
+- [x] 3.3 Add create/edit form for tool types (admin only)
+- [x] 3.4 Add delete confirmation dialog
+- [x] 3.5 Add route to router
+- [x] 3.6 Add navigation link in app shell
+
+## 4. Verification and Testing
+
+- [x] 4.1 Run backend quality gates (`pytest`, `ruff`, `mypy`)
+- [x] 4.2 Run frontend quality gates (`npm test`, `typecheck`, `lint`, `build`)
+- [x] 4.3 Test CRUD operations manually
+- [x] 4.4 Verify built-in types are seeded
+- [x] 4.5 Update this tasks file with completed checkboxes

openspec/specs/tool-types-definition/spec.md

@@ -0,0 +1,100 @@
+## ADDED Requirements
+
+### Requirement: Tool Type Model
+
+The system SHALL provide a `ToolType` model to store tool definitions.
+
+#### Scenario: Model structure
+- GIVEN a tool type definition
+- THEN the model SHALL have:
+  - `id`: UUID primary key
+  - `name`: unique string (e.g., "code-server")
+  - `display_name`: human-readable string (e.g., "VS Code Server")
+  - `description`: optional text
+  - `compose_template`: Docker Compose YAML string
+  - `required_variables`: list of required template variables
+  - `is_builtin`: boolean flag for system-defined types
+  - `created_at`/`updated_at`: timestamps
+
+### Requirement: CRUD API Endpoints
+
+The system SHALL provide REST API endpoints for tool type management.
+
+#### Scenario: List tool types
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types
+- THEN the system returns all tool types (built-in and custom)
+- AND returns 200 OK
+
+#### Scenario: Create tool type
+- GIVEN an admin user
+- WHEN they POST /api/tool-types with valid data
+- THEN the system creates a new tool type
+- AND validates the compose template YAML
+- AND validates all required variables are present in template
+- AND returns 201 Created with the new tool type
+
+#### Scenario: Get tool type
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types/{id}
+- THEN the system returns the tool type details
+- AND returns 200 OK
+
+#### Scenario: Update tool type
+- GIVEN an admin user
+- WHEN they PUT /api/tool-types/{id} with valid data
+- THEN the system updates the tool type
+- AND re-validates the compose template
+- AND returns 200 OK with updated tool type
+
+#### Scenario: Delete tool type
+- GIVEN an admin user
+- WHEN they DELETE /api/tool-types/{id}
+- THEN the system deletes the tool type
+- AND prevents deletion of built-in types
+- AND returns 204 No Content
+
+### Requirement: Template Variable Substitution
+
+The system SHALL support variable substitution in Docker Compose templates.
+
+#### Scenario: Supported variables
+- GIVEN a compose template with variables
+- THEN the system SHALL support:
+  - `{{REPO_PATH}}` - absolute path to repository
+  - `{{PROJECT_NAME}}` - project name
+  - `{{USER_ID}}` - user's UUID
+  - `{{TOOL_NAME}}` - tool instance name
+
+#### Scenario: Variable validation
+- GIVEN a new tool type with required variables
+- WHEN the template is created or updated
+- THEN the system validates all required variables exist in the template
+- AND returns 400 Bad Request if variables are missing
+
+### Requirement: Built-in Tool Types
+
+The system SHALL seed common tool types on first startup.
+
+#### Scenario: Default tool types
+- GIVEN a fresh database
+- WHEN the application starts
+- THEN the system creates built-in tool types:
+  - code-server (VS Code in browser)
+  - jupyter-notebook (Jupyter Lab)
+
+### Requirement: Compose Template Validation
+
+The system SHALL validate Docker Compose templates.
+
+#### Scenario: YAML validation
+- GIVEN a compose template string
+- WHEN creating or updating a tool type
+- THEN the system parses the YAML
+- AND returns 400 Bad Request if YAML is invalid
+
+#### Scenario: Required structure
+- GIVEN a valid YAML compose template
+- THEN the system SHALL require:
+  - `services` key present
+  - At least one service defined