refactor(server): introduce services layer with typed Server model

First step of the incremental migration spelled out in ADR-0007 (which
supersedes ADR-0004's "no services layer" stance). Sets up the two new
packages and converts the four most-used server subcommands as a
proof of concept.

New layout:
- orca_cli/models/server.py — TypedDict view of the Nova server payload
  covering the fields orca actually reads (standard names + the
  OS-EXT-* / OS-SRV-USG / os-extended-volumes colon-prefixed keys).
- orca_cli/services/server.py — ServerService wraps OrcaClient and owns
  /servers URL construction. Methods: find/find_all (paginated read),
  get, delete, action, start, stop, reboot. The list operation is
  named find/find_all so list[Server] annotations on sibling methods
  resolve to the builtin instead of the method itself.

Migrated commands:
- server list, server show, server delete, server reboot
The remaining 30+ subcommands continue to call OrcaClient directly
until they're each migrated in their own commit; ADR-0007 tracks
progress.

Drive-by:
- print_list signature widened from list[dict] to list (any sequence
  of mapping-like items, so TypedDict instances pass).
- server_show's local fields annotation widened from list[tuple[str,
  str]] to list[tuple[str, Any]] — the second element is whatever the
  Nova field returns, stringified by print_detail.
- ADR-0004 marked Superseded by ADR-0007; mkdocs nav and the ADR
  index updated.

Author: kallioli

docs/adr/0004-no-services-layer.md

@@ -1,6 +1,6 @@
 # ADR-0004: No services layer (yet)
 
-**Status**: Accepted
+**Status**: Superseded by [ADR-0007](0007-incremental-services-layer.md)
 **Date**: 2026-04-20
 
 ## Context

docs/adr/0007-incremental-services-layer.md

@@ -0,0 +1,78 @@
+# ADR-0007: Incremental services layer with typed models
+
+**Status**: Accepted
+**Date**: 2026-04-20
+**Supersedes**: [ADR-0004](0004-no-services-layer.md)
+
+## Context
+
+ADR-0004 deferred the services layer because the cost of refactoring all
+63 command modules at once was disproportionate to the immediate gain.
+Two months later the friction it predicted has materialised:
+
+- 740-odd raw `client.get/post/...` calls scattered across commands made
+  the recent N+1 hunt (cleanup, watch, export) harder than it should
+  have been: each fix had to be re-derived from the URL string.
+- The `dict[str, Any]` access pattern (2 136 `.get()` calls) means
+  `srv.get("nmae", "")` typos slip through to runtime; mypy can't help
+  because everything is `Any`.
+- Tests mock at the `OrcaClient` boundary; they assert on the URL string
+  passed to `client.get`. Renaming an endpoint or changing pagination
+  scheme breaks the assertions in cosmetic ways.
+
+The original concern — multi-day refactor with high regression risk —
+remains valid only if we attempt the migration in one shot.
+
+## Decision
+
+Introduce two new layers, **incrementally, one resource at a time**:
+
+- `orca_cli/models/<resource>.py` — `TypedDict`s describing the subset
+  of each Nova/Cinder/Neutron/etc. payload that orca actually reads.
+  `total=False` everywhere — fields are added as commands need them.
+- `orca_cli/services/<resource>.py` — a class wrapping `OrcaClient` that
+  exposes typed methods (`list`, `get`, `delete`, `reboot`, ...) and
+  owns the URL construction for that resource.
+
+Migration order is driven by pain, not by alphabetical resource name.
+The first migration is `server` (66 raw HTTP calls, 2235 LOC, the most
+exercised module). Each migration ships as one commit per command being
+refactored, never a "rewrite the whole module" PR. Commands that haven't
+been migrated keep calling `OrcaClient` directly — there is no flag day.
+
+The criteria for *not* introducing a service for a given resource:
+
+- Single-call wrapper (`get_token`, `get_catalog`) where the service
+  would just be a one-liner over the client. Stay direct.
+- Resource that orca only reads, never writes, with one or two calls
+  total. The service overhead exceeds the gain.
+
+## Consequences
+
+- **Positive**: typed return values mean autocomplete, mypy catches
+  field-name typos, and refactors propagate to compile-time errors.
+- **Positive**: URL construction lives in one place per resource; an
+  OpenStack version bump touches `services/<resource>.py`, not 30
+  command handlers.
+- **Positive**: tests can assert on `service.list.return_value =
+  [<typed Server>]` rather than mocking `client.get` URL-strings.
+  Less brittle, more readable.
+- **Negative / trade-off**: the codebase has *two* patterns for several
+  weeks (or months) until every resource is migrated. The boundary is
+  visible — a command either imports `services.X` or calls `client.get`
+  directly. We accept the ugliness; a flag-day rewrite was the
+  alternative we already rejected.
+- **Negative / trade-off**: `TypedDict` doesn't enforce field presence
+  at runtime — `srv["status"]` still raises `KeyError` if missing. The
+  contract is "*if* this field exists, *then* it has this type". For
+  presence guarantees we'd need `dataclass` + factory functions; that
+  conversion can come later if the runtime safety pays off.
+
+## Migration tracking
+
+When migrating a resource, leave a one-line entry below so future ADR
+readers can see how far along the work is.
+
+- 2026-04-20 — `server`: ServerService + Server TypedDict, four commands
+  migrated (`list`, `show`, `delete`, `reboot`). Remaining 30+ server
+  commands still call `OrcaClient` directly.

docs/adr/README.md

@@ -33,6 +33,7 @@ of the documentation.
 - [ADR-0001 — Lazy command registration](0001-lazy-command-registration.md)
 - [ADR-0002 — Dual-format configuration file](0002-dual-format-config-file.md)
 - [ADR-0003 — Auth-type auto-detection](0003-auth-type-auto-detection.md)
-- [ADR-0004 — No services layer (yet)](0004-no-services-layer.md)
+- [ADR-0004 — No services layer (yet)](0004-no-services-layer.md) *(superseded by ADR-0007)*
 - [ADR-0005 — Durable, atomic token cache](0005-durable-token-cache.md)
 - [ADR-0006 — Idempotent-only HTTP retries](0006-idempotent-only-retries.md)
+- [ADR-0007 — Incremental services layer with typed models](0007-incremental-services-layer.md)

mkdocs.yml

@@ -131,3 +131,4 @@ nav:
       - 0004 — No services layer (yet): adr/0004-no-services-layer.md
       - 0005 — Durable token cache: adr/0005-durable-token-cache.md
       - 0006 — Idempotent-only retries: adr/0006-idempotent-only-retries.md
+      - 0007 — Incremental services layer: adr/0007-incremental-services-layer.md

orca_cli/commands/server.py

@@ -22,6 +22,7 @@
 from orca_cli.core.output import console, output_options, print_detail, print_list
 from orca_cli.core.validators import validate_id
 from orca_cli.core.waiter import wait_for_resource
+from orca_cli.services.server import ServerService
 
 
 @click.group()
@@ -39,11 +40,8 @@ def server(ctx: click.Context) -> None:
 @click.pass_context
 def server_list(ctx: click.Context, limit: int, output_format: str, columns: tuple[str, ...], fit_width: bool, max_width: int | None, noindent: bool) -> None:
     """List servers."""
-    client = ctx.find_object(OrcaContext).ensure_client()
-    url = f"{client.compute_url}/servers/detail"
-    data = client.get(url, params={"limit": limit})
-
-    servers = data.get("servers", [])
+    service = ServerService(ctx.find_object(OrcaContext).ensure_client())
+    servers = service.find(limit=limit)
 
     def _addresses(srv: dict) -> str:
         parts = []
@@ -82,11 +80,8 @@ def _flavor(srv: dict) -> str:
 @click.pass_context
 def server_show(ctx: click.Context, server_id: str, output_format: str, columns: tuple[str, ...], fit_width: bool, max_width: int | None, noindent: bool) -> None:
     """Show server details."""
-    client = ctx.find_object(OrcaContext).ensure_client()
-    url = f"{client.compute_url}/servers/{server_id}"
-    data = client.get(url)
-
-    srv = data.get("server", data)
+    service = ServerService(ctx.find_object(OrcaContext).ensure_client())
+    srv = service.get(server_id)
 
     # Power state mapping (Nova integer → label)
     power_states = {
@@ -98,7 +93,7 @@ def server_show(ctx: click.Context, server_id: str, output_format: str, columns:
         7: "Suspended",
     }
 
-    fields: list[tuple[str, str]] = []
+    fields: list[tuple[str, Any]] = []
 
     fields.append(("ID", srv.get("id", "")))
     fields.append(("Name", srv.get("name", "")))
@@ -396,27 +391,29 @@ def server_delete(ctx: click.Context, server_id: str, yes: bool, dry_run: bool,
     """Delete a server."""
     orca_ctx = ctx.find_object(OrcaContext)
     client = orca_ctx.ensure_client()
-    url = f"{client.compute_url}/servers/{server_id}"
+    service = ServerService(client)
 
     if dry_run:
-        data = client.get(url)
-        srv = data.get("server", data)
+        srv = service.get(server_id)
         console.print("[yellow]Would delete server:[/yellow]")
         console.print(f"  ID:     {srv.get('id', server_id)}")
         console.print(f"  Name:   {srv.get('name', '—')}")
         console.print(f"  Status: {srv.get('status', '—')}")
-        console.print(f"  Image:  {srv.get('image', {}).get('id', '—') if isinstance(srv.get('image'), dict) else '—'}")
+        image = srv.get("image")
+        image_id = image.get("id", "—") if isinstance(image, dict) else "—"
+        console.print(f"  Image:  {image_id}")
         return
 
     if not yes:
         click.confirm(f"Delete server {server_id}?", abort=True)
 
-    client.delete(url)
+    service.delete(server_id)
     cache.invalidate(orca_ctx.profile, "servers")
 
     if wait:
         wait_for_resource(
-            client, url, "server", "DELETED",
+            client, f"{client.compute_url}/servers/{server_id}",
+            "server", "DELETED",
             label=f"Server {server_id}",
             delete_mode=True,
         )
@@ -466,10 +463,11 @@ def server_stop(ctx: click.Context, server_id: str, wait: bool) -> None:
 @click.pass_context
 def server_reboot(ctx: click.Context, server_id: str, hard: bool, wait: bool) -> None:
     """Reboot a server."""
+    client = ctx.find_object(OrcaContext).ensure_client()
+    ServerService(client).reboot(server_id, hard=hard)
     reboot_type = "HARD" if hard else "SOFT"
-    _server_action(ctx, server_id, {"reboot": {"type": reboot_type}}, f"Reboot ({reboot_type})")
+    console.print(f"[green]Reboot ({reboot_type}) request sent for {server_id}.[/green]")
     if wait:
-        client = ctx.find_object(OrcaContext).ensure_client()
         wait_for_resource(client, f"{client.compute_url}/servers/{server_id}",
                           "server", "ACTIVE", label=f"Server {server_id}")
 

orca_cli/core/output.py

@@ -57,7 +57,7 @@ def _json_indent(noindent: bool) -> int | None:
 
 
 def print_list(
-    items: list[dict],
+    items: list,
     column_defs: list[tuple],
     *,
     title: str = "",

orca_cli/models/__init__.py

@@ -0,0 +1,6 @@
+"""Typed models for OpenStack API responses (subset used by orca).
+
+Models are TypedDicts with ``total=False`` — the field set we actually
+read from each resource, not an exhaustive schema. Adding a field that
+mypy starts to flag means widening the type, not silencing the error.
+"""

orca_cli/models/server.py

@@ -0,0 +1,59 @@
+"""Typed view of the Nova server resource (only the fields orca reads)."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ServerFlavor(TypedDict, total=False):
+    id: str
+    original_name: str
+    vcpus: int
+    ram: int
+    disk: int
+
+
+class ServerAddress(TypedDict, total=False):
+    addr: str
+    version: int
+
+
+# Server uses the alternative TypedDict syntax because Nova exposes a
+# handful of OS-EXT-* fields whose names contain colons — those can't
+# be expressed as Python identifiers in the class form.
+Server = TypedDict(
+    "Server",
+    {
+        "id": str,
+        "name": str,
+        "status": str,
+        "flavor": ServerFlavor,
+        "image": dict,
+        "addresses": dict,
+        "key_name": str,
+        "created": str,
+        "updated": str,
+        "user_id": str,
+        "tenant_id": str,
+        "hostId": str,
+        "accessIPv4": str,
+        "accessIPv6": str,
+        "config_drive": str,
+        "progress": int,
+        "metadata": dict,
+        "tags": list,
+        "security_groups": list,
+        "os-extended-volumes:volumes_attached": list,
+        "OS-EXT-STS:vm_state": str,
+        "OS-EXT-STS:task_state": str,
+        "OS-EXT-STS:power_state": int,
+        "OS-EXT-AZ:availability_zone": str,
+        "OS-EXT-SRV-ATTR:host": str,
+        "OS-EXT-SRV-ATTR:hypervisor_hostname": str,
+        "OS-EXT-SRV-ATTR:instance_name": str,
+        "OS-DCF:diskConfig": str,
+        "OS-SRV-USG:launched_at": str,
+        "OS-SRV-USG:terminated_at": str,
+    },
+    total=False,
+)

orca_cli/services/__init__.py

@@ -0,0 +1,10 @@
+"""Service layer — high-level operations on OpenStack resources.
+
+Each service wraps an OrcaClient and exposes typed methods that map to
+the underlying API endpoints. Command handlers in ``orca_cli/commands/``
+delegate to a service rather than calling ``client.get/post/...``
+directly; the trade-offs are documented in ADR-0007.
+
+Services are introduced incrementally — only the resources whose
+command modules have been migrated have a corresponding service yet.
+"""

orca_cli/services/server.py

@@ -0,0 +1,65 @@
+"""High-level operations on Nova servers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from orca_cli.core.client import OrcaClient
+from orca_cli.models.server import Server
+
+
+class ServerService:
+    """Typed wrapper around the Nova ``/servers`` endpoints.
+
+    Owns URL construction; commands import this service instead of
+    building ``f"{client.compute_url}/servers/..."`` strings themselves.
+    Retry, auth, and rate-limit handling live in OrcaClient — the
+    service is purely a translation layer between the Nova API and the
+    typed model.
+    """
+
+    def __init__(self, client: OrcaClient) -> None:
+        self._client = client
+        self._base = f"{client.compute_url}/servers"
+
+    # ── reads ──────────────────────────────────────────────────────────
+
+    def find(self, limit: int = 50) -> list[Server]:
+        """Return up to ``limit`` servers with their detail payload.
+
+        Named ``find`` rather than ``list`` to avoid shadowing the
+        builtin within the class scope (mypy then can't resolve
+        ``list[Server]`` annotations on sibling methods).
+        """
+        data = self._client.get(f"{self._base}/detail", params={"limit": limit})
+        return data.get("servers", [])
+
+    def find_all(self, page_size: int = 1000) -> list[Server]:
+        """Paginate through every server in the project (no silent cap)."""
+        return self._client.paginate(f"{self._base}/detail", "servers",
+                                     page_size=page_size)
+
+    def get(self, server_id: str) -> Server:
+        """Fetch one server by ID. Raises APIError if not found."""
+        data = self._client.get(f"{self._base}/{server_id}")
+        return data.get("server", data)
+
+    # ── writes ─────────────────────────────────────────────────────────
+
+    def delete(self, server_id: str) -> None:
+        """Issue an asynchronous delete; the server transitions to
+        DELETED state."""
+        self._client.delete(f"{self._base}/{server_id}")
+
+    def action(self, server_id: str, body: dict[str, Any]) -> None:
+        """POST a Nova action verb (e.g. ``{"reboot": {"type": "SOFT"}}``)."""
+        self._client.post(f"{self._base}/{server_id}/action", json=body)
+
+    def start(self, server_id: str) -> None:
+        self.action(server_id, {"os-start": None})
+
+    def stop(self, server_id: str) -> None:
+        self.action(server_id, {"os-stop": None})
+
+    def reboot(self, server_id: str, *, hard: bool = False) -> None:
+        self.action(server_id, {"reboot": {"type": "HARD" if hard else "SOFT"}})