fix: subclass all the exceptions (#6)

Closes #5.

Author: tseaver

docs/reference/api.md

@@ -56,14 +56,18 @@ non-default parent is added).
 
 | Member | Purpose |
 | --- | --- |
-| `validate_room_id(room_id)` | enforce the room-id / path-segment rule (`ROOM_ID_RE`); raises `AddRoomError` |
+| `validate_room_id(room_id)` | enforce the room-id / path-segment rule (`ROOM_ID_RE`); raises `BadRoomId` |
 | `resolve_project(project_dir)` | resolve + verify the stack root (has `COMPOSE_FILE` and `INSTALLATION_FILE`) |
 | `resolve_package_name(project, override)` | the stack's own package (inferred from `src/<pkg>/tools.py`) or `DEFAULT_PACKAGE_NAME` |
 | `room_parent_candidates(project)` | the `room_paths` container entries a caller can offer as a `parent_path` (or `["./rooms"]` when absent) |
 | `install_room(project, room_id, *, config_text, prompt_text=None, parent_path, force=False, dry_run=False)` | write the room dir from a rendered `config_text` (+ optional prompt) under `parent_path` and wire `room_paths` |
 | `install_room_from(project, room_id, src_dir, *, parent_path, force=False, dry_run=False)` | the same, but *copy* the `src_dir` template tree (multi-file); the caller patches the copied files afterward |
 | `RoomInstalled(config_path, path_action)` | the install outcome (alias `RoomInstall` kept for back-compat) |
-| `AddRoomError` | user-facing error with message-factory classmethods (incl. `bad_room_id`, `parent_is_room`) |
+| `AddRoomError` | base class for user-facing errors |
+| `ComposeNotFound(AddRoomError)` | No `docker-compose.yaml` found |
+| `NotAStack(AddRoomError)` | target lacks required template-generated files |
+| `BadRoomId(AddRoomError)` | invalid room ID syntac |
+| `ParentIsRoom(AddRoomError)` | room directory exists |
 | `RoomExists(AddRoomError)` | Allows users to catch this error specifically |
 | `ADDED` / `UNCHANGED` / `COVERED` | the `installation.TargetAction` members, re-exported |
 | `ROOMS_PARENT_ENTRY` | the `./rooms` default-discovery container |

src/soliplex_plumber/rooms.py

@@ -61,36 +61,40 @@
 
 
 class AddRoomError(Exception):
-    """A user-facing error (printed without a traceback).
+    """Base class for user-facing errors."""
 
-    Message construction lives in these classmethod factories so call sites
-    read ``raise AddRoomError.<reason>(...)`` with no inline message string.
-    """
 
-    @classmethod
-    def compose_not_found(cls, path):
-        return cls(
+class ComposeNotFound(AddRoomError):
+    def __init__(self, path):
+        self.path = path
+        super().__init__(
             f"no {COMPOSE_FILE} at {path} "
             "(run with --project-dir pointing at the stack directory)"
         )
 
-    @classmethod
-    def not_a_stack(cls, path):
-        return cls(
+
+class NotAStack(AddRoomError):
+    def __init__(self, path):
+        self.path = path
+        super().__init__(
             f"{path} is not a generated Soliplex stack: missing "
             f"'{INSTALLATION_FILE}'"
         )
 
-    @classmethod
-    def bad_room_id(cls, room_id):
-        return cls(
+
+class BadRoomId(AddRoomError):
+    def __init__(self, room_id):
+        self.room_id = room_id
+        super().__init__(
             f"room id {room_id!r} must match {ROOM_ID_RE.pattern} "
             "(letters, digits, '.', '_', '-'; no leading dot)"
         )
 
-    @classmethod
-    def parent_is_room(cls, path):
-        return cls(
+
+class ParentIsRoom(AddRoomError):
+    def __init__(self, path):
+        self.path = path
+        super().__init__(
             f"parent_path {path} is itself a room (has a room_config.yaml); "
             "pass a container directory to install rooms into"
         )
@@ -104,16 +108,16 @@ def __init__(self, path):
 
 def validate_room_id(room_id: str) -> None:
     if not ROOM_ID_RE.match(room_id):
-        raise AddRoomError.bad_room_id(room_id)
+        raise BadRoomId(room_id)
 
 
 def resolve_project(project_dir: str) -> pathlib.Path:
     """Return the resolved stack root, or raise if it is not a stack."""
     project = pathlib.Path(project_dir).resolve()
     if not (project / COMPOSE_FILE).is_file():
-        raise AddRoomError.compose_not_found(project / COMPOSE_FILE)
+        raise ComposeNotFound(project / COMPOSE_FILE)
     if not (project / INSTALLATION_FILE).is_file():
-        raise AddRoomError.not_a_stack(project)
+        raise NotAStack(project)
     return project
 
 
@@ -246,7 +250,7 @@ def _install_room(
     room, or when the room dir already exists and ``force`` is false."""
     env = project / ENVIRONMENT_DIR
     if (env / parent_path / "room_config.yaml").is_file():
-        raise AddRoomError.parent_is_room(env / parent_path)
+        raise ParentIsRoom(env / parent_path)
     room_dir = env / parent_path / room_id
     config_path = room_dir / "room_config.yaml"
     if room_dir.exists() and not force:

tests/unit/test_rooms.py

@@ -106,7 +106,7 @@ def test_validate_room_id_accepts(room_id):
 
 @pytest.mark.parametrize("room_id", ["", ".hidden", "a/b", "a b", "../x"])
 def test_validate_room_id_rejects(room_id):
-    with pytest.raises(rooms.AddRoomError, match="must match"):
+    with pytest.raises(rooms.BadRoomId):
         rooms.validate_room_id(room_id)
 
 
@@ -121,17 +121,17 @@ def test_resolve_project_ok(tmp_path):
     assert result == project.resolve()
 
 
-def test_resolve_project_no_compose(tmp_path):
+def test_resolve_project_compose_not_found(tmp_path):
     project = _make_stack(tmp_path, compose=False)
 
-    with pytest.raises(rooms.AddRoomError, match="docker-compose.yml"):
+    with pytest.raises(rooms.ComposeNotFound):
         rooms.resolve_project(str(project))
 
 
 def test_resolve_project_not_a_stack(tmp_path):
     project = _make_stack(tmp_path, installation=False)
 
-    with pytest.raises(rooms.AddRoomError, match="not a generated"):
+    with pytest.raises(rooms.NotAStack):
         rooms.resolve_project(str(project))
 
 
@@ -381,7 +381,7 @@ def test_install_room_rejects_parent_that_is_a_room(tmp_path):
     # ./rooms is a room
     _write_text(rooms_dir / "room_config.yaml", rooms_id_yaml)
 
-    with pytest.raises(rooms.AddRoomError, match="itself a room"):
+    with pytest.raises(rooms.ParentIsRoom):
         rooms.install_room(
             project, "handbook", config_text=X_ID_YAML, parent_path="./rooms"
         )