BUG-HUNT: [spec-alignment] Default database location deviates from specification #1288

New issue

Open

opened 2026-04-02 08:51:24 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 08:51:24 +00:00

Owner

Bug Report: [spec-alignment] — Default database location deviates from specification

Severity Assessment

Impact: The database is created in the current working directory by default, which is often not the desired behavior. This can lead to data loss if the user runs the application from different directories. The specification states that the database should be stored in a dedicated application data directory in the user's home directory.
Likelihood: High. This will affect all users who do not explicitly configure the database URL.
Priority: Medium

Location

File: src/cleveragents/config/settings.py
Function/Class: Settings
Lines: 251-254

Description

The database_url setting in settings.py defaults to sqlite:///cleveragents.db, which is a relative path. This causes the database to be created in the current working directory. The specification states that the database should be located at ~/.cleveragents/cleveragents.db.

Evidence

# src/cleveragents/config/settings.py:251
    database_url: str = Field(
        default="sqlite:///cleveragents.db",
        validation_alias=AliasChoices("CLEVERAGENTS_DATABASE_URL"),
    )

Expected Behavior

The default database URL should point to a location within the user's home directory, as specified in the documentation. For example: sqlite:///{Path.home()}/.cleveragents/cleveragents.db. The application should ensure that the directory ~/.cleveragents is created if it does not exist.

Actual Behavior

The database is created in the current working directory.

Suggested Fix

Update the default database_url to use a path in the user's home directory. The pathlib.Path.home() method can be used to get the user's home directory.

from pathlib import Path

# ...

    database_url: str = Field(
        default_factory=lambda: f"sqlite:///{Path.home()}/.cleveragents/cleveragents.db",
        validation_alias=AliasChoices("CLEVERAGENTS_DATABASE_URL"),
    )

Metadata

Branch: fix/spec-alignment-default-database-location
Commit Message: fix(config): set default database_url to ~/.cleveragents/cleveragents.db per specification
Milestone: v3.3.0
Parent Epic: #362

Subtasks

Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail that asserts the default database_url resolves to a path inside the user's home directory (i.e., contains /.cleveragents/cleveragents.db)
Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail that asserts the ~/.cleveragents/ directory is created automatically if it does not exist when the settings are initialised
Replace the default="sqlite:///cleveragents.db" with a default_factory that uses pathlib.Path.home() to construct the absolute path ~/.cleveragents/cleveragents.db
Add logic (e.g., a Pydantic model_validator or a startup hook) to ensure the ~/.cleveragents/ directory is created with Path.mkdir(parents=True, exist_ok=True) before the database engine is initialised
Remove the @tdd_expected_fail tags from both TDD scenarios once the fix is in place and verify they pass
Run nox -e typecheck to confirm no type regressions
Run nox -e unit_tests to confirm all Behave tests pass
Run nox -e coverage_report to confirm coverage remains ≥ 97%
Run nox (all default sessions) and fix any errors

Definition of Done

Both @tdd_expected_fail TDD capture scenarios are committed first and demonstrate the incorrect default path
The database_url field in Settings uses default_factory to produce an absolute path under ~/.cleveragents/
The ~/.cleveragents/ directory is created automatically on first use if it does not exist
Both TDD scenarios pass without @tdd_expected_fail after the fix
No regressions in existing settings or database initialisation tests
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests, nox -e coverage_report)
Coverage >= 97%
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Bug Report: [spec-alignment] — Default database location deviates from specification ### Severity Assessment - **Impact**: The database is created in the current working directory by default, which is often not the desired behavior. This can lead to data loss if the user runs the application from different directories. The specification states that the database should be stored in a dedicated application data directory in the user's home directory. - **Likelihood**: High. This will affect all users who do not explicitly configure the database URL. - **Priority**: Medium ### Location - **File**: `src/cleveragents/config/settings.py` - **Function/Class**: `Settings` - **Lines**: 251-254 ### Description The `database_url` setting in `settings.py` defaults to `sqlite:///cleveragents.db`, which is a relative path. This causes the database to be created in the current working directory. The specification states that the database should be located at `~/.cleveragents/cleveragents.db`. ### Evidence ```python # src/cleveragents/config/settings.py:251 database_url: str = Field( default="sqlite:///cleveragents.db", validation_alias=AliasChoices("CLEVERAGENTS_DATABASE_URL"), ) ``` ### Expected Behavior The default database URL should point to a location within the user's home directory, as specified in the documentation. For example: `sqlite:///{Path.home()}/.cleveragents/cleveragents.db`. The application should ensure that the directory `~/.cleveragents` is created if it does not exist. ### Actual Behavior The database is created in the current working directory. ### Suggested Fix Update the default `database_url` to use a path in the user's home directory. The `pathlib.Path.home()` method can be used to get the user's home directory. ```python from pathlib import Path # ... database_url: str = Field( default_factory=lambda: f"sqlite:///{Path.home()}/.cleveragents/cleveragents.db", validation_alias=AliasChoices("CLEVERAGENTS_DATABASE_URL"), ) ``` ### Category spec-alignment --- ## Metadata - **Branch**: `fix/spec-alignment-default-database-location` - **Commit Message**: `fix(config): set default database_url to ~/.cleveragents/cleveragents.db per specification` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Subtasks - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` that asserts the default `database_url` resolves to a path inside the user's home directory (i.e., contains `/.cleveragents/cleveragents.db`) - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` that asserts the `~/.cleveragents/` directory is created automatically if it does not exist when the settings are initialised - [ ] Replace the `default="sqlite:///cleveragents.db"` with a `default_factory` that uses `pathlib.Path.home()` to construct the absolute path `~/.cleveragents/cleveragents.db` - [ ] Add logic (e.g., a Pydantic `model_validator` or a startup hook) to ensure the `~/.cleveragents/` directory is created with `Path.mkdir(parents=True, exist_ok=True)` before the database engine is initialised - [ ] Remove the `@tdd_expected_fail` tags from both TDD scenarios once the fix is in place and verify they pass - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox -e unit_tests` to confirm all Behave tests pass - [ ] Run `nox -e coverage_report` to confirm coverage remains ≥ 97% - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done - [ ] Both `@tdd_expected_fail` TDD capture scenarios are committed first and demonstrate the incorrect default path - [ ] The `database_url` field in `Settings` uses `default_factory` to produce an absolute path under `~/.cleveragents/` - [ ] The `~/.cleveragents/` directory is created automatically on first use if it does not exist - [ ] Both TDD scenarios pass without `@tdd_expected_fail` after the fix - [ ] No regressions in existing settings or database initialisation tests - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`, `nox -e coverage_report`) - [ ] Coverage >= 97% - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

freemo added the

labels

2026-04-02 08:51:44 +00:00

freemo added this to the v3.3.0 milestone