docs: resolve pending commit links of MIL-002

Task: MIL-002#7

Doxyfile

@@ -130,10 +130,10 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = src README.md
+INPUT                  = src
 INPUT_ENCODING         = UTF-8
 INPUT_FILE_ENCODING    =
-FILE_PATTERNS          = *.py *.md
+FILE_PATTERNS           = *.py
 RECURSIVE              = YES
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
@@ -147,7 +147,7 @@ INPUT_FILTER           =
 FILTER_PATTERNS        =
 FILTER_SOURCE_FILES    = NO
 FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE = README.md
+USE_MDFILE_AS_MAINPAGE   =
 IMPLICIT_DIR_DOCS      = YES
 FORTRAN_COMMENT_AFTER  = 72
 #---------------------------------------------------------------------------

docs/artifact-registry.md

@@ -16,7 +16,7 @@ document of a type. `Primary File` may contain a glob (e.g.
 | PP | Project Plan | docs/project-plan.md | 002 |
 | MIL | Milestone / Gateway | docs/milestones/*.md | 004 |
 | DICT | Domain Dictionary | docs/dictionary.md | 002 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 008 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 009 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
 
 ## Languages

docs/sqa/reviews/rc-008-mil-002-code.md

@@ -0,0 +1,64 @@
+# SQA Review Record
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-008 |
+| CrossReference | [MIL-002], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [463ffc3] |
+
+---
+
+# Code review for MIL-002
+
+## Artifact Under Review
+
+- Instance reviewed: `src/password_manager/` and `tests/` (19 modules, 37 tests) as of the MIL-002 pull request, delivering [MIL-002]
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a
+- Language reviewer: none
+- Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | Packages and modules are snake_case, classes PascalCase (`JsonPasswordRepository`, `PasswordEntry`), constants UPPER_SNAKE. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose (`EntryNotFoundError`, `find_password`, `confirm_save`); no cryptic abbreviations. |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff format --check` reports 26 files already formatted; `ruff check` reports 0 findings and the sources contain no `noqa`. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | ruff rule set `ANN` is enabled and passes, so every signature is annotated. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No bare `except`; repository and view model catch the narrowest domain errors and re-raise with `raise ... from error`. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; ruff `B` rules pass. |
+| 7 | Files, locks and connections are managed with context managers | Pass | The repository opens the JSON file with `with self._path.open(...)`. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Every public module, class and function has a Doxygen docstring (`@brief`, `@param`, `@return`, `@throws`); `doxygen Doxyfile` runs without warnings. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | No `print` and no logging; passwords are shown only in the window messages the course requires. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | No DCD exists (no use case modelled, see Project Plan Open Issues); the class set follows the clean-architecture layers and is recorded in MIL-002 tasks. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | `python -m pytest` runs 37 tests (unit, integration, e2e) named for behaviour, using `tmp_path` and fakes; none touch the network or depend on order. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | No type checker is configured. The single `Any` (JSON object values) has a justifying comment. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies = []`; pytest and ruff are the only dev extras and both are used. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Constants, messages and JSON keys are defined once in `constants.py`; validation of empty fields is in the use cases only. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `domain` imports only `constants` and the standard library; `application` imports `domain`; `presentation` imports no `infrastructure` module (grep); only `main.py` composes them. No import cycle. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Each class has one job (entry, generator, use cases, JSON repository, view model, view); the use cases depend on the `PasswordRepository` protocol and receive the implementation. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | `domain`, `application`, `infrastructure`, `presentation` packages under `src/password_manager/` and `unit`, `integration`, `e2e` under `tests/`; imports point inward. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | All file and folder names are English snake_case with no spaces. |
+
+## Overall Verdict
+
+Go — every Mandatory criterion passes.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | - |
+
+---
+
+[MIL-002]: ../../milestones/mil-002-password-manager-features.md
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[463ffc3]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-password-manager/commit/463ffc3d4a477affa3ac45f1c33c4241a62677e1

docs/sqa/traceability-matrix.md

@@ -31,6 +31,7 @@ an artifact instance is created or reviewed.
 | [MIL-002] | MIL | en | it | [BC-001], [MIL-001] | [MIL-003] | [RC-005] |
 | [MIL-003] | MIL | en | it | [BC-001], [MIL-002] | - | [RC-006] |
 | `src/`, `tests/` (MIL-001 code) | PY | - | - | [MIL-001] | - | [RC-007] |
+| `src/`, `tests/` (MIL-002 code) | PY | - | - | [MIL-002] | - | [RC-008] |
 
 ## Coverage Notes
 
@@ -58,3 +59,4 @@ an artifact instance is created or reviewed.
 [RC-006]: ./reviews/rc-006-mil-003.md
 [53f56ee]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-password-manager/commit/53f56eeb143d810b91da23f743a53a32207f81bb
 [RC-007]: ./reviews/rc-007-mil-001-code.md
+[RC-008]: ./reviews/rc-008-mil-002-code.md

src/password_manager/__main__.py

@@ -0,0 +1,8 @@
+"""@brief Entry point for `python -m password_manager`.
+
+@file __main__.py
+"""
+
+from password_manager.main import main
+
+main()

src/password_manager/application/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/application/ports.py

@@ -0,0 +1,31 @@
+"""@brief Ports the use cases need from the outside.
+
+@file ports.py
+"""
+
+from typing import Protocol
+
+from password_manager.domain.password_entry import PasswordEntry
+
+
+class PasswordRepository(Protocol):
+    """@brief Storage of password entries."""
+
+    def add(self, entry: PasswordEntry) -> None:
+        """@brief Store an entry, keeping every other entry.
+
+        @param entry The entry to store; replaces one for the same website.
+        @throws InvalidDataFileError The stored data has an unexpected format.
+        """
+        ...
+
+    def find(self, website: str) -> PasswordEntry:
+        """@brief Look an entry up.
+
+        @param website The website to look for.
+        @return The stored entry.
+        @throws DataFileNotFoundError There is no storage yet.
+        @throws EntryNotFoundError The website has no entry.
+        @throws InvalidDataFileError The stored data has an unexpected format.
+        """
+        ...

src/password_manager/application/use_cases.py

@@ -0,0 +1,76 @@
+"""@brief Use cases of the password manager.
+
+@file use_cases.py
+"""
+
+import random
+
+from password_manager.application.ports import PasswordRepository
+from password_manager.domain.errors import EmptyFieldError
+from password_manager.domain.password_entry import PasswordEntry
+from password_manager.domain.password_generator import generate_password
+
+
+class SavePasswordEntry:
+    """@brief Validate and store a password entry."""
+
+    def __init__(self, repository: PasswordRepository) -> None:
+        """@brief Create the use case.
+
+        @param repository Where entries are stored.
+        """
+        self._repository = repository
+
+    def execute(self, website: str, email: str, password: str) -> None:
+        """@brief Store the entry.
+
+        @param website Website of the entry.
+        @param email E-mail address or user name.
+        @param password The password.
+        @throws EmptyFieldError A field is empty.
+        """
+        if not (website.strip() and email.strip() and password.strip()):
+            raise EmptyFieldError
+        self._repository.add(PasswordEntry(website.strip(), email, password))
+
+
+class FindPasswordEntry:
+    """@brief Look up the entry of a website."""
+
+    def __init__(self, repository: PasswordRepository) -> None:
+        """@brief Create the use case.
+
+        @param repository Where entries are stored.
+        """
+        self._repository = repository
+
+    def execute(self, website: str) -> PasswordEntry:
+        """@brief Find the entry.
+
+        @param website Website to look for.
+        @return The stored entry.
+        @throws EmptyFieldError The website is empty.
+        @throws DataFileNotFoundError There is no storage yet.
+        @throws EntryNotFoundError The website has no entry.
+        """
+        if not website.strip():
+            raise EmptyFieldError
+        return self._repository.find(website.strip())
+
+
+class GeneratePassword:
+    """@brief Produce a new random password."""
+
+    def __init__(self, rng: random.Random | None = None) -> None:
+        """@brief Create the use case.
+
+        @param rng Random source; secure by default.
+        """
+        self._rng = rng
+
+    def execute(self) -> str:
+        """@brief Generate a password.
+
+        @return The new password.
+        """
+        return generate_password(self._rng)

src/password_manager/constants.py

@@ -16,6 +16,7 @@ DATA_FILE_PATH = Path(
 JSON_INDENT = 4  ##< Indentation of the written JSON, for readability.
 KEY_EMAIL = "email"  ##< JSON key of an entry's e-mail address.
 KEY_PASSWORD = "password"  ##< JSON key of an entry's password.
+FILE_ENCODING = "utf-8"  ##< Text encoding of the data file.
 
 # Password generator
 LETTERS = string.ascii_letters  ##< Letters a password may use.
@@ -36,6 +37,17 @@ DEFAULT_EMAIL = "name@example.com"  ##< E-mail address the form starts with.
 ENTRY_WIDTH_WIDE = 35  ##< Width in characters of the e-mail and add fields.
 ENTRY_WIDTH_NARROW = 21  ##< Width in characters of the website and password fields.
 
+# Logo (a padlock drawn with canvas shapes)
+LOGO_BACKGROUND = "white"  ##< Canvas background colour.
+LOGO_BODY_COLOR = "#2b6cb0"  ##< Fill of the padlock body.
+LOGO_SHACKLE_COLOR = "#4a5568"  ##< Outline colour of the padlock shackle.
+LOGO_KEYHOLE_COLOR = "white"  ##< Fill of the keyhole.
+LOGO_SHACKLE_WIDTH = 12  ##< Line width of the shackle, in pixels.
+LOGO_BODY_BOX = (50, 100, 150, 180)  ##< Padlock body rectangle (x0, y0, x1, y1).
+LOGO_SHACKLE_BOX = (65, 30, 135, 170)  ##< Bounding box of the shackle arc.
+LOGO_KEYHOLE_BOX = (92, 125, 108, 141)  ##< Bounding box of the keyhole circle.
+LOGO_KEYHOLE_SLOT = (97, 138, 103, 160)  ##< Rectangle of the keyhole slot.
+
 # Labels and messages
 LABEL_WEBSITE = "Website:"
 LABEL_EMAIL = "Email/Username:"
@@ -54,3 +66,5 @@ MESSAGE_CONFIRM_SAVE = (
     "Password: {password}\nIs it ok to save?"
 )
 MESSAGE_DETAILS = "Email: {email}\nPassword: {password}"
+MESSAGE_INVALID_DATA_FILE = "The data file has an unexpected format."
+MESSAGE_SAVED = "Details for {website} were saved."

src/password_manager/domain/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/domain/errors.py

@@ -0,0 +1,32 @@
+"""@brief Errors raised by the business rules of the password manager.
+
+@file errors.py
+"""
+
+
+class PasswordManagerError(Exception):
+    """@brief Base class of every error the password manager raises on purpose."""
+
+
+class EmptyFieldError(PasswordManagerError):
+    """@brief A required field was left empty."""
+
+
+class DataFileNotFoundError(PasswordManagerError):
+    """@brief The data file does not exist, so nothing can be looked up."""
+
+
+class InvalidDataFileError(PasswordManagerError):
+    """@brief The data file exists but does not hold the expected structure."""
+
+
+class EntryNotFoundError(PasswordManagerError):
+    """@brief No entry is stored for a website."""
+
+    def __init__(self, website: str) -> None:
+        """@brief Create the error.
+
+        @param website The website that was looked up.
+        """
+        super().__init__(website)
+        self.website = website

src/password_manager/domain/password_entry.py

@@ -0,0 +1,15 @@
+"""@brief The password entry of the domain.
+
+@file password_entry.py
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class PasswordEntry:
+    """@brief The credentials stored for one website."""
+
+    website: str  ##< The website the credentials belong to.
+    email: str  ##< E-mail address or user name.
+    password: str  ##< The password.

src/password_manager/domain/password_generator.py

@@ -0,0 +1,29 @@
+"""@brief Generation of random passwords.
+
+@file password_generator.py
+"""
+
+import random
+
+from password_manager import constants
+
+
+def generate_password(rng: random.Random | None = None) -> str:
+    """@brief Build a shuffled password of letters, symbols and digits.
+
+    @param rng Random source; a cryptographically secure one when omitted.
+    @return The generated password; each class count is within its bounds.
+    """
+    source = rng if rng is not None else random.SystemRandom()
+    characters = (
+        _pick(source, constants.LETTERS, constants.MIN_LETTERS, constants.MAX_LETTERS)
+        + _pick(source, constants.SYMBOLS, constants.MIN_SYMBOLS, constants.MAX_SYMBOLS)
+        + _pick(source, constants.DIGITS, constants.MIN_DIGITS, constants.MAX_DIGITS)
+    )
+    source.shuffle(characters)
+    return "".join(characters)
+
+
+def _pick(source: random.Random, alphabet: str, low: int, high: int) -> list[str]:
+    count = source.randint(low, high)
+    return [source.choice(alphabet) for _ in range(count)]

src/password_manager/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/infrastructure/persistence/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/infrastructure/persistence/json_password_repository.py

@@ -0,0 +1,79 @@
+"""@brief Password repository that keeps entries in a JSON file.
+
+@file json_password_repository.py
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from password_manager import constants
+from password_manager.domain.errors import (
+    DataFileNotFoundError,
+    EntryNotFoundError,
+    InvalidDataFileError,
+)
+from password_manager.domain.password_entry import PasswordEntry
+
+
+class JsonPasswordRepository:
+    """@brief Stores entries as {website: {"email": ..., "password": ...}}."""
+
+    def __init__(self, path: Path) -> None:
+        """@brief Create the repository.
+
+        @param path Location of the JSON file.
+        """
+        self._path = path
+
+    def add(self, entry: PasswordEntry) -> None:
+        """@brief Store an entry; a missing or empty file is created or rewritten.
+
+        @param entry The entry to store.
+        @throws InvalidDataFileError The file holds JSON that is not an object.
+        """
+        try:
+            data = self._load()
+        except (FileNotFoundError, json.JSONDecodeError):
+            data = {}
+        data[entry.website] = {
+            constants.KEY_EMAIL: entry.email,
+            constants.KEY_PASSWORD: entry.password,
+        }
+        with self._path.open("w", encoding=constants.FILE_ENCODING, newline="\n") as f:
+            json.dump(data, f, indent=constants.JSON_INDENT)
+
+    def find(self, website: str) -> PasswordEntry:
+        """@brief Look an entry up.
+
+        @param website Website to look for.
+        @return The stored entry.
+        @throws DataFileNotFoundError The file does not exist.
+        @throws EntryNotFoundError The website has no entry (or the file is empty).
+        @throws InvalidDataFileError The file has an unexpected structure.
+        """
+        try:
+            data = self._load()
+        except FileNotFoundError as error:
+            raise DataFileNotFoundError from error
+        except json.JSONDecodeError as error:
+            raise EntryNotFoundError(website) from error
+        if website not in data:
+            raise EntryNotFoundError(website)
+        details = data[website]
+        try:
+            return PasswordEntry(
+                website,
+                details[constants.KEY_EMAIL],
+                details[constants.KEY_PASSWORD],
+            )
+        except (KeyError, TypeError) as error:
+            raise InvalidDataFileError from error
+
+    # Any: the values of a JSON object are unchecked until `find` validates them.
+    def _load(self) -> dict[str, Any]:
+        with self._path.open("r", encoding=constants.FILE_ENCODING) as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            raise InvalidDataFileError
+        return data

src/password_manager/main.py

@@ -0,0 +1,39 @@
+"""@brief Composition root: wires the layers together and runs the window.
+
+@file main.py
+"""
+
+import tkinter as tk
+
+from password_manager import constants
+from password_manager.application.use_cases import (
+    FindPasswordEntry,
+    GeneratePassword,
+    SavePasswordEntry,
+)
+from password_manager.infrastructure.persistence.json_password_repository import (
+    JsonPasswordRepository,
+)
+from password_manager.presentation.features.password_manager import (
+    password_manager_view as view_module,
+)
+from password_manager.presentation.features.password_manager import (
+    password_manager_view_model as view_model_module,
+)
+
+
+def main() -> None:
+    """@brief Build the application and run the Tk main loop."""
+    repository = JsonPasswordRepository(constants.DATA_FILE_PATH)
+    view_model = view_model_module.PasswordManagerViewModel(
+        SavePasswordEntry(repository),
+        FindPasswordEntry(repository),
+        GeneratePassword(),
+    )
+    root = tk.Tk()
+    view_module.PasswordManagerView(root, view_model)
+    root.mainloop()
+
+
+if __name__ == "__main__":
+    main()

src/password_manager/presentation/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/presentation/features/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/presentation/features/password_manager/__init__.py

@@ -0,0 +1 @@
+"""@brief Package marker."""

src/password_manager/presentation/features/password_manager/password_manager_view.py

@@ -0,0 +1,156 @@
+"""@brief Tkinter view of the password manager screen.
+
+@file password_manager_view.py
+"""
+
+import tkinter as tk
+from tkinter import messagebox
+
+from password_manager import constants
+from password_manager.presentation.features.password_manager import (
+    password_manager_view_model as view_model_module,
+)
+
+
+class PasswordManagerView:
+    """@brief The window: shows the fields and raises events to the view model."""
+
+    def __init__(
+        self, root: tk.Tk, view_model: view_model_module.PasswordManagerViewModel
+    ) -> None:
+        """@brief Build the widgets on a root window.
+
+        @param root The Tk root window.
+        @param view_model The view model the events are forwarded to.
+        """
+        self._root = root
+        self._view_model = view_model
+        self._view_model.bind_ui(self._copy_to_clipboard, self._confirm_save)
+        root.title(constants.WINDOW_TITLE)
+        root.config(padx=constants.WINDOW_PADDING, pady=constants.WINDOW_PADDING)
+        self._build_logo()
+        self._build_form()
+
+    @property
+    def website_entry(self) -> tk.Entry:
+        """@return The website input."""
+        return self._website_entry
+
+    @property
+    def email_entry(self) -> tk.Entry:
+        """@return The e-mail input."""
+        return self._email_entry
+
+    @property
+    def password_entry(self) -> tk.Entry:
+        """@return The password input."""
+        return self._password_entry
+
+    def generate_password(self) -> None:
+        """@brief Fill the password field with a new password (and copy it)."""
+        password = self._view_model.generate_password()
+        self._password_entry.delete(0, tk.END)
+        self._password_entry.insert(0, password)
+
+    def save(self) -> None:
+        """@brief Ask the view model to store the entered details."""
+        result = self._view_model.save(
+            self._website_entry.get(),
+            self._email_entry.get(),
+            self._password_entry.get(),
+        )
+        if result is None:
+            return
+        self._show(result)
+        if result.clear_fields:
+            self._clear_fields()
+
+    def find_password(self) -> None:
+        """@brief Show the stored details of the entered website."""
+        self._show(self._view_model.find_password(self._website_entry.get()))
+
+    def _build_logo(self) -> None:
+        size = constants.LOGO_SIZE
+        canvas = tk.Canvas(
+            self._root,
+            width=size,
+            height=size,
+            bg=constants.LOGO_BACKGROUND,
+            highlightthickness=0,
+        )
+        canvas.create_arc(
+            *constants.LOGO_SHACKLE_BOX,
+            start=0,
+            extent=180,
+            style=tk.ARC,
+            outline=constants.LOGO_SHACKLE_COLOR,
+            width=constants.LOGO_SHACKLE_WIDTH,
+        )
+        canvas.create_rectangle(
+            *constants.LOGO_BODY_BOX,
+            fill=constants.LOGO_BODY_COLOR,
+            outline=constants.LOGO_BODY_COLOR,
+        )
+        canvas.create_oval(
+            *constants.LOGO_KEYHOLE_BOX,
+            fill=constants.LOGO_KEYHOLE_COLOR,
+            outline=constants.LOGO_KEYHOLE_COLOR,
+        )
+        canvas.create_rectangle(
+            *constants.LOGO_KEYHOLE_SLOT,
+            fill=constants.LOGO_KEYHOLE_COLOR,
+            outline=constants.LOGO_KEYHOLE_COLOR,
+        )
+        canvas.grid(row=0, column=1)
+
+    def _build_form(self) -> None:
+        root = self._root
+        tk.Label(root, text=constants.LABEL_WEBSITE).grid(row=1, column=0)
+        tk.Label(root, text=constants.LABEL_EMAIL).grid(row=2, column=0)
+        tk.Label(root, text=constants.LABEL_PASSWORD).grid(row=3, column=0)
+
+        self._website_entry = tk.Entry(root, width=constants.ENTRY_WIDTH_NARROW)
+        self._website_entry.grid(row=1, column=1, sticky="EW")
+        self._website_entry.focus()
+        self._email_entry = tk.Entry(root, width=constants.ENTRY_WIDTH_WIDE)
+        self._email_entry.grid(row=2, column=1, columnspan=2, sticky="EW")
+        self._email_entry.insert(0, constants.DEFAULT_EMAIL)
+        self._password_entry = tk.Entry(root, width=constants.ENTRY_WIDTH_NARROW)
+        self._password_entry.grid(row=3, column=1, sticky="EW")
+
+        self._search_button = tk.Button(
+            root, text=constants.BUTTON_SEARCH, command=self.find_password
+        )
+        self._search_button.grid(row=1, column=2, sticky="EW")
+        self._generate_button = tk.Button(
+            root, text=constants.BUTTON_GENERATE, command=self.generate_password
+        )
+        self._generate_button.grid(row=3, column=2, sticky="EW")
+        self._add_button = tk.Button(
+            root,
+            text=constants.BUTTON_ADD,
+            width=constants.ENTRY_WIDTH_WIDE,
+            command=self.save,
+        )
+        self._add_button.grid(row=4, column=1, columnspan=2, sticky="EW")
+
+    def _copy_to_clipboard(self, text: str) -> None:
+        self._root.clipboard_clear()
+        self._root.clipboard_append(text)
+
+    @staticmethod
+    def _confirm_save(message: str) -> bool:
+        return bool(
+            messagebox.askokcancel(title=constants.WINDOW_TITLE, message=message)
+        )
+
+    @staticmethod
+    def _show(result: view_model_module.ActionResult) -> None:
+        if result.is_error:
+            messagebox.showwarning(title=result.title, message=result.message)
+        else:
+            messagebox.showinfo(title=result.title, message=result.message)
+
+    def _clear_fields(self) -> None:
+        self._website_entry.delete(0, tk.END)
+        self._password_entry.delete(0, tk.END)

src/password_manager/presentation/features/password_manager/password_manager_view_model.py

@@ -0,0 +1,154 @@
+"""@brief View model of the password manager screen (no tkinter here).
+
+@file password_manager_view_model.py
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from password_manager import constants
+from password_manager.application.use_cases import (
+    FindPasswordEntry,
+    GeneratePassword,
+    SavePasswordEntry,
+)
+from password_manager.domain.errors import (
+    DataFileNotFoundError,
+    EmptyFieldError,
+    EntryNotFoundError,
+    InvalidDataFileError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ActionResult:
+    """@brief What the view shows after an action."""
+
+    title: str  ##< Title of the message box.
+    message: str  ##< Text of the message box.
+    is_error: bool  ##< True when the box is a warning rather than information.
+    clear_fields: bool = False  ##< True when the view clears website and password.
+
+
+def _ignore_clipboard(text: str) -> None:
+    """@brief Default clipboard: discards the text until the view binds one."""
+
+
+def _decline_save(message: str) -> bool:
+    """@brief Default confirmation: declines until the view binds a dialog."""
+    return False
+
+
+class PasswordManagerViewModel:
+    """@brief Data and commands of the password manager screen."""
+
+    def __init__(
+        self,
+        save_entry: SavePasswordEntry,
+        find_entry: FindPasswordEntry,
+        generate: GeneratePassword,
+        copy_to_clipboard: Callable[[str], None] = _ignore_clipboard,
+        confirm_save: Callable[[str], bool] = _decline_save,
+    ) -> None:
+        """@brief Create the view model.
+
+        @param save_entry Use case that stores an entry.
+        @param find_entry Use case that looks an entry up.
+        @param generate Use case that generates a password.
+        @param copy_to_clipboard Puts text on the clipboard.
+        @param confirm_save Asks the user to confirm a save; True means ok.
+        """
+        self._save_entry = save_entry
+        self._find_entry = find_entry
+        self._generate = generate
+        self._copy_to_clipboard = copy_to_clipboard
+        self._confirm_save = confirm_save
+
+    def bind_ui(
+        self,
+        copy_to_clipboard: Callable[[str], None],
+        confirm_save: Callable[[str], bool],
+    ) -> None:
+        """@brief Hand the view's clipboard and confirmation dialog to the model.
+
+        @param copy_to_clipboard Puts text on the clipboard.
+        @param confirm_save Asks the user to confirm a save; True means ok.
+        """
+        self._copy_to_clipboard = copy_to_clipboard
+        self._confirm_save = confirm_save
+
+    def generate_password(self) -> str:
+        """@brief Generate a password and copy it to the clipboard.
+
+        @return The generated password.
+        """
+        password = self._generate.execute()
+        self._copy_to_clipboard(password)
+        return password
+
+    def save(self, website: str, email: str, password: str) -> ActionResult | None:
+        """@brief Confirm and store the entry.
+
+        @param website Website field.
+        @param email E-mail field.
+        @param password Password field.
+        @return A result to show, or None when the user cancelled.
+        """
+        if not (website.strip() and email.strip() and password.strip()):
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_EMPTY_FIELDS, True
+            )
+        question = constants.MESSAGE_CONFIRM_SAVE.format(email=email, password=password)
+        if not self._confirm_save(question):
+            return None
+        try:
+            self._save_entry.execute(website, email, password)
+        except EmptyFieldError:
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_EMPTY_FIELDS, True
+            )
+        except InvalidDataFileError:
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_INVALID_DATA_FILE, True
+            )
+        else:
+            return ActionResult(
+                constants.TITLE_SAVED,
+                constants.MESSAGE_SAVED.format(website=website.strip()),
+                False,
+                clear_fields=True,
+            )
+
+    def find_password(self, website: str) -> ActionResult:
+        """@brief Look up the credentials of a website.
+
+        @param website Website field.
+        @return The result to show.
+        """
+        try:
+            entry = self._find_entry.execute(website)
+        except EmptyFieldError:
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_EMPTY_FIELDS, True
+            )
+        except DataFileNotFoundError:
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_NO_DATA_FILE, True
+            )
+        except EntryNotFoundError as error:
+            return ActionResult(
+                constants.TITLE_OOPS,
+                constants.MESSAGE_NO_DETAILS.format(website=error.website),
+                True,
+            )
+        except InvalidDataFileError:
+            return ActionResult(
+                constants.TITLE_OOPS, constants.MESSAGE_INVALID_DATA_FILE, True
+            )
+        return ActionResult(
+            entry.website,
+            constants.MESSAGE_DETAILS.format(
+                email=entry.email, password=entry.password
+            ),
+            False,
+        )

tests/e2e/test_password_manager_window.py

@@ -0,0 +1,65 @@
+import tkinter as tk
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+from password_manager import constants
+from password_manager.application.use_cases import (
+    FindPasswordEntry,
+    GeneratePassword,
+    SavePasswordEntry,
+)
+from password_manager.infrastructure.persistence.json_password_repository import (
+    JsonPasswordRepository,
+)
+from password_manager.presentation.features.password_manager import (
+    password_manager_view as view_module,
+)
+from password_manager.presentation.features.password_manager import (
+    password_manager_view_model as view_model_module,
+)
+
+
+@pytest.fixture
+def root() -> Iterator[tk.Tk]:
+    try:
+        window = tk.Tk()
+    except tk.TclError:
+        pytest.skip("no display available")
+    window.withdraw()
+    yield window
+    window.destroy()
+
+
+def test_save_then_search_through_window(
+    root: tk.Tk, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    shown: list[str] = []
+    monkeypatch.setattr(view_module.messagebox, "askokcancel", lambda **_: True)
+    monkeypatch.setattr(
+        view_module.messagebox, "showinfo", lambda **kw: shown.append(kw["message"])
+    )
+    repository = JsonPasswordRepository(tmp_path / "data.json")
+    view = view_module.PasswordManagerView(
+        root,
+        view_model_module.PasswordManagerViewModel(
+            SavePasswordEntry(repository),
+            FindPasswordEntry(repository),
+            GeneratePassword(),
+        ),
+    )
+    view.website_entry.insert(0, "example.com")
+    view.generate_password()
+    password = view.password_entry.get()
+    assert root.clipboard_get() == password
+
+    view.save()
+
+    assert view.website_entry.get() == ""
+    assert view.password_entry.get() == ""
+    view.website_entry.insert(0, "example.com")
+    view.find_password()
+    assert shown[-1] == constants.MESSAGE_DETAILS.format(
+        email=constants.DEFAULT_EMAIL, password=password
+    )

tests/integration/test_json_password_repository.py

@@ -0,0 +1,111 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from password_manager.domain.errors import (
+    DataFileNotFoundError,
+    EntryNotFoundError,
+    InvalidDataFileError,
+)
+from password_manager.domain.password_entry import PasswordEntry
+from password_manager.infrastructure.persistence.json_password_repository import (
+    JsonPasswordRepository,
+)
+
+ENTRY = PasswordEntry("example.com", "me@x.org", "pw1")
+
+
+def test_add_writes_nested_json_and_reads_back(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    repository = JsonPasswordRepository(path)
+
+    repository.add(ENTRY)
+
+    assert json.loads(path.read_text("utf-8")) == {
+        "example.com": {"email": "me@x.org", "password": "pw1"}
+    }
+    assert repository.find("example.com") == ENTRY
+
+
+def test_add_uses_indent_of_four(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    JsonPasswordRepository(path).add(ENTRY)
+
+    assert '\n    "example.com"' in path.read_text("utf-8")
+
+
+def test_add_keeps_existing_entries(tmp_path: Path) -> None:
+    repository = JsonPasswordRepository(tmp_path / "data.json")
+    other = PasswordEntry("other.org", "o@x.org", "pw2")
+    repository.add(ENTRY)
+
+    repository.add(other)
+
+    assert repository.find("example.com") == ENTRY
+    assert repository.find("other.org") == other
+
+
+def test_add_creates_missing_file(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    assert not path.exists()
+
+    JsonPasswordRepository(path).add(ENTRY)
+
+    assert path.exists()
+
+
+def test_add_rewrites_empty_file(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    path.write_text("", encoding="utf-8")
+
+    JsonPasswordRepository(path).add(ENTRY)
+
+    assert JsonPasswordRepository(path).find("example.com") == ENTRY
+
+
+def test_add_rewrites_invalid_json(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    path.write_text("{not json", encoding="utf-8")
+
+    JsonPasswordRepository(path).add(ENTRY)
+
+    assert JsonPasswordRepository(path).find("example.com") == ENTRY
+
+
+def test_add_refuses_json_that_is_not_an_object(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    path.write_text("[1, 2]", encoding="utf-8")
+
+    with pytest.raises(InvalidDataFileError):
+        JsonPasswordRepository(path).add(ENTRY)
+    assert path.read_text("utf-8") == "[1, 2]"
+
+
+def test_find_raises_when_file_missing(tmp_path: Path) -> None:
+    with pytest.raises(DataFileNotFoundError):
+        JsonPasswordRepository(tmp_path / "data.json").find("example.com")
+
+
+def test_find_raises_when_website_absent(tmp_path: Path) -> None:
+    repository = JsonPasswordRepository(tmp_path / "data.json")
+    repository.add(ENTRY)
+
+    with pytest.raises(EntryNotFoundError):
+        repository.find("nope.com")
+
+
+def test_find_raises_not_found_on_empty_file(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    path.write_text("", encoding="utf-8")
+
+    with pytest.raises(EntryNotFoundError):
+        JsonPasswordRepository(path).find("example.com")
+
+
+def test_find_raises_when_entry_lacks_keys(tmp_path: Path) -> None:
+    path = tmp_path / "data.json"
+    path.write_text('{"example.com": {"email": "e"}}', encoding="utf-8")
+
+    with pytest.raises(InvalidDataFileError):
+        JsonPasswordRepository(path).find("example.com")

tests/unit/application/test_use_cases.py

@@ -0,0 +1,68 @@
+import random
+
+import pytest
+from conftest import FakePasswordRepository
+
+from password_manager.application.use_cases import (
+    FindPasswordEntry,
+    GeneratePassword,
+    SavePasswordEntry,
+)
+from password_manager.domain.errors import (
+    DataFileNotFoundError,
+    EmptyFieldError,
+    EntryNotFoundError,
+)
+from password_manager.domain.password_entry import PasswordEntry
+
+
+def test_save_stores_entry(repository: FakePasswordRepository) -> None:
+    SavePasswordEntry(repository).execute("example.com", "me@x.org", "pw")
+
+    assert repository.entries["example.com"] == PasswordEntry(
+        "example.com", "me@x.org", "pw"
+    )
+
+
+@pytest.mark.parametrize(
+    ("website", "email", "password"),
+    [("", "e", "p"), ("w", "", "p"), ("w", "e", ""), ("  ", "e", "p")],
+)
+def test_save_rejects_empty_field(
+    repository: FakePasswordRepository, website: str, email: str, password: str
+) -> None:
+    with pytest.raises(EmptyFieldError):
+        SavePasswordEntry(repository).execute(website, email, password)
+    assert repository.entries == {}
+
+
+def test_find_returns_entry(repository: FakePasswordRepository) -> None:
+    SavePasswordEntry(repository).execute("example.com", "me@x.org", "pw")
+
+    entry = FindPasswordEntry(repository).execute("example.com")
+
+    assert entry.email == "me@x.org"
+
+
+def test_find_raises_when_website_unknown(
+    repository: FakePasswordRepository,
+) -> None:
+    with pytest.raises(EntryNotFoundError):
+        FindPasswordEntry(repository).execute("nope.com")
+
+
+def test_find_raises_when_no_data_file() -> None:
+    with pytest.raises(DataFileNotFoundError):
+        FindPasswordEntry(FakePasswordRepository(has_file=False)).execute("a.com")
+
+
+def test_find_rejects_empty_website(repository: FakePasswordRepository) -> None:
+    with pytest.raises(EmptyFieldError):
+        FindPasswordEntry(repository).execute("")
+
+
+def test_generate_uses_given_random_source() -> None:
+    first = GeneratePassword(random.Random(1)).execute()
+    second = GeneratePassword(random.Random(1)).execute()
+
+    assert first == second

tests/unit/conftest.py

@@ -0,0 +1,30 @@
+"""Shared fakes of the ports for the unit tests."""
+
+import pytest
+
+from password_manager.domain.errors import DataFileNotFoundError, EntryNotFoundError
+from password_manager.domain.password_entry import PasswordEntry
+
+
+class FakePasswordRepository:
+    """In-memory PasswordRepository; `has_file` False mimics a missing file."""
+
+    def __init__(self, has_file: bool = True) -> None:
+        self.entries: dict[str, PasswordEntry] = {}
+        self.has_file = has_file
+
+    def add(self, entry: PasswordEntry) -> None:
+        self.entries[entry.website] = entry
+        self.has_file = True
+
+    def find(self, website: str) -> PasswordEntry:
+        if not self.has_file:
+            raise DataFileNotFoundError
+        if website not in self.entries:
+            raise EntryNotFoundError(website)
+        return self.entries[website]
+
+
+@pytest.fixture
+def repository() -> FakePasswordRepository:
+    return FakePasswordRepository()

tests/unit/domain/test_password_generator.py

@@ -0,0 +1,35 @@
+import random
+
+from password_manager import constants
+from password_manager.domain.password_generator import generate_password
+
+
+def _count(password: str, alphabet: str) -> int:
+    return sum(1 for char in password if char in alphabet)
+
+
+def test_generate_password_length_within_bounds() -> None:
+    low = constants.MIN_LETTERS + constants.MIN_SYMBOLS + constants.MIN_DIGITS
+    high = constants.MAX_LETTERS + constants.MAX_SYMBOLS + constants.MAX_DIGITS
+    for seed in range(50):
+        assert low <= len(generate_password(random.Random(seed))) <= high
+
+
+def test_generate_password_uses_all_three_classes_within_bounds() -> None:
+    for seed in range(50):
+        password = generate_password(random.Random(seed))
+        letters = _count(password, constants.LETTERS)
+        symbols = _count(password, constants.SYMBOLS)
+        digits = _count(password, constants.DIGITS)
+        assert constants.MIN_LETTERS <= letters <= constants.MAX_LETTERS
+        assert constants.MIN_SYMBOLS <= symbols <= constants.MAX_SYMBOLS
+        assert constants.MIN_DIGITS <= digits <= constants.MAX_DIGITS
+        assert letters + symbols + digits == len(password)
+
+
+def test_generate_password_is_reproducible_with_same_seed() -> None:
+    assert generate_password(random.Random(7)) == generate_password(random.Random(7))
+
+
+def test_generate_password_default_source_works() -> None:
+    assert generate_password()

tests/unit/presentation/test_password_manager_view_model.py

@@ -0,0 +1,121 @@
+import random
+
+from conftest import FakePasswordRepository
+
+from password_manager import constants
+from password_manager.application.use_cases import (
+    FindPasswordEntry,
+    GeneratePassword,
+    SavePasswordEntry,
+)
+from password_manager.presentation.features.password_manager import (
+    password_manager_view_model as view_model_module,
+)
+
+
+class FakeUi:
+    """Records clipboard writes and questions, answers with a fixed choice."""
+
+    def __init__(self, answer: bool = True) -> None:
+        self.answer = answer
+        self.clipboard: list[str] = []
+        self.questions: list[str] = []
+
+    def copy(self, text: str) -> None:
+        self.clipboard.append(text)
+
+    def confirm(self, message: str) -> bool:
+        self.questions.append(message)
+        return self.answer
+
+
+def _make(
+    repository: FakePasswordRepository, ui: FakeUi
+) -> view_model_module.PasswordManagerViewModel:
+    return view_model_module.PasswordManagerViewModel(
+        SavePasswordEntry(repository),
+        FindPasswordEntry(repository),
+        GeneratePassword(random.Random(3)),
+        ui.copy,
+        ui.confirm,
+    )
+
+
+def test_generate_password_copies_to_clipboard(
+    repository: FakePasswordRepository,
+) -> None:
+    ui = FakeUi()
+
+    password = _make(repository, ui).generate_password()
+
+    assert ui.clipboard == [password]
+
+
+def test_save_stores_and_clears_fields_after_confirmation(
+    repository: FakePasswordRepository,
+) -> None:
+    ui = FakeUi(answer=True)
+
+    result = _make(repository, ui).save("a.com", "me@x.org", "pw")
+
+    assert result is not None
+    assert not result.is_error
+    assert result.clear_fields
+    assert "a.com" in repository.entries
+    assert "me@x.org" in ui.questions[0]
+
+
+def test_save_does_nothing_when_user_cancels(
+    repository: FakePasswordRepository,
+) -> None:
+    result = _make(repository, FakeUi(answer=False)).save("a.com", "e", "pw")
+
+    assert result is None
+    assert repository.entries == {}
+
+
+def test_save_refuses_empty_field_without_asking(
+    repository: FakePasswordRepository,
+) -> None:
+    ui = FakeUi()
+
+    result = _make(repository, ui).save("", "e", "pw")
+
+    assert result is not None
+    assert result.is_error
+    assert result.message == constants.MESSAGE_EMPTY_FIELDS
+    assert not result.clear_fields
+    assert ui.questions == []
+
+
+def test_find_password_found(repository: FakePasswordRepository) -> None:
+    model = _make(repository, FakeUi())
+    model.save("a.com", "me@x.org", "pw")
+
+    result = model.find_password("a.com")
+
+    assert not result.is_error
+    assert result.message == constants.MESSAGE_DETAILS.format(
+        email="me@x.org", password="pw"
+    )
+
+
+def test_find_password_website_not_present(
+    repository: FakePasswordRepository,
+) -> None:
+    result = _make(repository, FakeUi()).find_password("b.com")
+
+    assert result.is_error
+    assert result.message == constants.MESSAGE_NO_DETAILS.format(website="b.com")
+
+
+def test_find_password_no_data_file() -> None:
+    model = _make(FakePasswordRepository(has_file=False), FakeUi())
+
+    assert model.find_password("a.com").message == constants.MESSAGE_NO_DATA_FILE
+
+
+def test_find_password_empty_website(repository: FakePasswordRepository) -> None:
+    result = _make(repository, FakeUi()).find_password(" ")
+
+    assert result.message == constants.MESSAGE_EMPTY_FIELDS