feat(share): support Manila shared file systems

Adds the missing parity with ``openstack share`` — the only
significant OpenStack service orca did not wrap. Lot 1 covers the
day-to-day surface (create/list/show/delete/set/extend/shrink,
access rules, snapshots, read-only types); admin-only flows
(share networks, servers, type create) are deferred to lot 2 if
demand surfaces.

- ``orca_cli/services/shared_file_system.FileShareService`` — pins
  ``X-OpenStack-Manila-API-Version: 2.51`` (Train, supports the
  unified ``/share-access-rules`` endpoint) and wraps every
  endpoint orca uses behind a typed method.
- ``orca_cli/models/shared_file_system`` — TypedDict views for
  Share, ShareAccessRule, ShareSnapshot, ShareType.
- ``orca_cli/commands/share`` — top-level group with three
  sub-groups (``access``, ``snapshot``, ``type``). Follows
  ADR-0008: ``noun [subnoun] verb`` from day one.
- ``orca_cli/core/client.share_url`` — catalog property with the
  same fallback pattern as ``volume_url``: tries ``sharev2``
  first, falls back to legacy ``share``. Raises a clear
  ``APIError`` if neither is in the catalogue (Manila not
  deployed).
- Tests: ``tests/test_services_shared_file_system.py`` (service-
  level, 28 tests, 99 % coverage on the service) +
  ``tests/test_share.py`` (command-level, 50+ tests on
  registration, body shape, parametrize on every leaf). 2643
  tests pass total, 87.93 % coverage.

No DevStack Manila instance available to smoke-test live; the
service tests lock URL/body/headers so the wire shape is covered
without one. When a Manila-enabled cloud is reachable, drop a
``tests/devstack/test_live_share_full.py`` mirroring the existing
live patterns.

Author: kallioli

orca_cli/commands/share.py

@@ -650,6 +650,25 @@ def rating_url(self) -> str:
         """CloudKitty (rating) public endpoint."""
         return self._endpoint_for("rating")
 
+    @property
+    def share_url(self) -> str:
+        """Manila (shared file systems) public endpoint.
+
+        Catalog type was renamed ``share`` → ``sharev2`` when Manila
+        adopted microversioning (2.0). Try the modern type first and
+        fall back so orca works against both eras of catalogue.
+        """
+        for service_type in ("sharev2", "share"):
+            try:
+                return self._endpoint_for(service_type)
+            except APIError:
+                continue
+        raise APIError(
+            0,
+            "Manila/shared-file-system endpoint not found in catalogue. "
+            "Check that Manila is deployed and the project has access.",
+        )
+
     # ── Generic HTTP helpers ──────────────────────────────────────────────────
 
     def _headers(self, extra: dict[str, str] | None = None,

orca_cli/core/client.py

@@ -0,0 +1,68 @@
+"""Typed views of Manila (shared file system) resources."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class Share(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    status: str
+    size: int
+    share_proto: str
+    share_type: str
+    share_type_name: str
+    share_network_id: str
+    share_group_id: str
+    snapshot_id: str
+    availability_zone: str
+    host: str
+    project_id: str
+    user_id: str
+    is_public: bool
+    access_rules_status: str
+    has_replicas: bool
+    replication_type: str
+    export_location: str
+    export_locations: list
+    created_at: str
+    metadata: dict
+
+
+class ShareAccessRule(TypedDict, total=False):
+    id: str
+    access_level: str       # "rw" | "ro"
+    access_type: str        # "ip" | "user" | "cert" | "cephx"
+    access_to: str
+    access_key: str         # only for CephFS
+    state: str              # "active" | "error" | "applying" | "denying"
+    share_id: str
+    created_at: str
+    updated_at: str
+    metadata: dict
+
+
+class ShareSnapshot(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    status: str
+    share_id: str
+    share_size: int
+    size: int
+    project_id: str
+    user_id: str
+    provider_location: str
+    created_at: str
+
+
+class ShareType(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    is_default: bool
+    is_public: bool
+    extra_specs: dict
+    required_extra_specs: dict

orca_cli/models/shared_file_system.py

@@ -0,0 +1,163 @@
+"""High-level operations on Manila (shared file system) resources.
+
+Manila uses a microversion header to opt into newer API features —
+orca pins ``X-OpenStack-Manila-API-Version: 2.51`` (OpenStack Train),
+which is old enough to be supported everywhere Manila ships, and new
+enough to expose the unified ``/share-access-rules`` endpoint instead
+of the legacy per-share action API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from orca_cli.core.client import OrcaClient
+from orca_cli.models.shared_file_system import (
+    Share,
+    ShareAccessRule,
+    ShareSnapshot,
+    ShareType,
+)
+
+# Microversion floor. Bump only with a clear reason: it directly
+# affects the response shape that orca's models assume.
+MANILA_MICROVERSION = "2.51"
+
+
+class FileShareService:
+    """Typed wrapper around Manila v2 endpoints."""
+
+    def __init__(self, client: OrcaClient) -> None:
+        self._client = client
+        self._base = client.share_url
+
+    # ── header injection ───────────────────────────────────────────────
+
+    def _h(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        h = {"X-OpenStack-Manila-API-Version": MANILA_MICROVERSION}
+        if extra:
+            h.update(extra)
+        return h
+
+    # ── shares ─────────────────────────────────────────────────────────
+
+    def find(self, *, detail: bool = True,
+             params: dict[str, Any] | None = None) -> list[Share]:
+        suffix = "/shares/detail" if detail else "/shares"
+        data = self._client.get(f"{self._base}{suffix}",
+                                params=params, headers=self._h())
+        return data.get("shares", [])
+
+    def get(self, share_id: str) -> Share:
+        data = self._client.get(f"{self._base}/shares/{share_id}",
+                                headers=self._h())
+        return data.get("share", data)
+
+    def create(self, body: dict[str, Any]) -> Share:
+        # Manila wraps the body under "share".
+        data = self._client.post(f"{self._base}/shares",
+                                 json={"share": body}, headers=self._h())
+        return data.get("share", data) if data else {}
+
+    def update(self, share_id: str, body: dict[str, Any]) -> Share:
+        data = self._client.put(f"{self._base}/shares/{share_id}",
+                                json={"share": body}, headers=self._h())
+        return data.get("share", data) if data else {}
+
+    def delete(self, share_id: str) -> None:
+        self._client.delete(f"{self._base}/shares/{share_id}",
+                            headers=self._h())
+
+    def extend(self, share_id: str, new_size: int) -> None:
+        """Grow a share to *new_size* GB."""
+        self._client.post(f"{self._base}/shares/{share_id}/action",
+                          json={"extend": {"new_size": new_size}},
+                          headers=self._h())
+
+    def shrink(self, share_id: str, new_size: int) -> None:
+        self._client.post(f"{self._base}/shares/{share_id}/action",
+                          json={"shrink": {"new_size": new_size}},
+                          headers=self._h())
+
+    # ── access rules (unified API, microversion ≥ 2.45) ────────────────
+
+    def find_access_rules(self, share_id: str) -> list[ShareAccessRule]:
+        data = self._client.get(
+            f"{self._base}/share-access-rules",
+            params={"share_id": share_id}, headers=self._h(),
+        )
+        return data.get("access_list", [])
+
+    def get_access_rule(self, access_id: str) -> ShareAccessRule:
+        data = self._client.get(
+            f"{self._base}/share-access-rules/{access_id}",
+            headers=self._h(),
+        )
+        return data.get("access", data)
+
+    def allow_access(self, share_id: str, access_type: str,
+                     access_to: str, *, access_level: str = "rw",
+                     metadata: dict | None = None) -> ShareAccessRule:
+        body: dict[str, Any] = {
+            "allow_access": {
+                "access_type": access_type,
+                "access_to": access_to,
+                "access_level": access_level,
+            }
+        }
+        if metadata:
+            body["allow_access"]["metadata"] = metadata
+        data = self._client.post(f"{self._base}/shares/{share_id}/action",
+                                 json=body, headers=self._h())
+        return data.get("access", data) if data else {}
+
+    def deny_access(self, share_id: str, access_id: str) -> None:
+        self._client.post(
+            f"{self._base}/shares/{share_id}/action",
+            json={"deny_access": {"access_id": access_id}},
+            headers=self._h(),
+        )
+
+    # ── snapshots ──────────────────────────────────────────────────────
+
+    def find_snapshots(self, *, detail: bool = True,
+                       params: dict[str, Any] | None = None) -> list[ShareSnapshot]:
+        suffix = "/snapshots/detail" if detail else "/snapshots"
+        data = self._client.get(f"{self._base}{suffix}",
+                                params=params, headers=self._h())
+        return data.get("snapshots", [])
+
+    def get_snapshot(self, snapshot_id: str) -> ShareSnapshot:
+        data = self._client.get(f"{self._base}/snapshots/{snapshot_id}",
+                                headers=self._h())
+        return data.get("snapshot", data)
+
+    def create_snapshot(self, share_id: str, *,
+                        name: str | None = None,
+                        description: str | None = None) -> ShareSnapshot:
+        body: dict[str, Any] = {"share_id": share_id}
+        if name:
+            body["name"] = name
+        if description:
+            body["description"] = description
+        data = self._client.post(f"{self._base}/snapshots",
+                                 json={"snapshot": body}, headers=self._h())
+        return data.get("snapshot", data) if data else {}
+
+    def delete_snapshot(self, snapshot_id: str) -> None:
+        self._client.delete(f"{self._base}/snapshots/{snapshot_id}",
+                            headers=self._h())
+
+    # ── types (read-only here; admin create lives in lot 2) ────────────
+
+    def find_types(self) -> list[ShareType]:
+        data = self._client.get(f"{self._base}/types", headers=self._h())
+        return data.get("share_types", [])
+
+    def get_type(self, type_id: str) -> ShareType:
+        data = self._client.get(f"{self._base}/types/{type_id}",
+                                headers=self._h())
+        return data.get("share_type", data)
+
+
+__all__ = ["FileShareService", "MANILA_MICROVERSION"]

orca_cli/services/shared_file_system.py

@@ -18,6 +18,7 @@
     "user", "volume", "watch", "zone", "placement", "alarm", "rating",
     "policy", "identity-provider", "federation-protocol", "mapping", "service-provider",
     "limit", "registered-limit", "access-rule", "token", "endpoint-group",
+    "share",
 ]