tasko 0.0.1__tar.gz

tasko-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pybass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tasko-0.0.1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: tasko
+Version: 0.0.1
+Summary: Personal task manager
+Author: pybass
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Requires-Dist: rich~=15.0
+Requires-Dist: textual~=8.2
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/pybass/tasko
+Project-URL: Issues, https://github.com/pybass/tasko/issues
+Description-Content-Type: text/markdown
+
+# tasko
+
+A personal task manager: a fast Textual TUI over local SQLite, with a minimal
+CLI for quick capture.
+
+## Usage
+
+`tasko` with no arguments launches the TUI — the primary interface, where all
+task and project management lives.
+
+The CLI is deliberately minimal (see
+[docs/architecture.md](docs/architecture.md) for why):
+
+```sh
+tasko add "fix nginx" -p infra   # quick capture from the shell
+tasko list                       # a quick look without launching the TUI
+```
+
+Data is a single SQLite file under `$XDG_DATA_HOME/tasko` (default
+`~/.local/share/tasko`); override the directory with `--data-dir` or the
+`TASKO_DATA_DIR` env var.
+
+## Design
+
+- [docs/architecture.md](docs/architecture.md) — layering (`core/` + `cli/` +
+  `tui/`), the TUI-first UI strategy, tool choices.
+- [docs/data-model.md](docs/data-model.md) — entities, the full SQL schema,
+  and the reasoning behind it.
+- [docs/non-goals.md](docs/non-goals.md) — features deliberately not built,
+  and why.
+
+## License
+
+[MIT](LICENSE)

tasko-0.0.1/README.md

@@ -0,0 +1,34 @@
+# tasko
+
+A personal task manager: a fast Textual TUI over local SQLite, with a minimal
+CLI for quick capture.
+
+## Usage
+
+`tasko` with no arguments launches the TUI — the primary interface, where all
+task and project management lives.
+
+The CLI is deliberately minimal (see
+[docs/architecture.md](docs/architecture.md) for why):
+
+```sh
+tasko add "fix nginx" -p infra   # quick capture from the shell
+tasko list                       # a quick look without launching the TUI
+```
+
+Data is a single SQLite file under `$XDG_DATA_HOME/tasko` (default
+`~/.local/share/tasko`); override the directory with `--data-dir` or the
+`TASKO_DATA_DIR` env var.
+
+## Design
+
+- [docs/architecture.md](docs/architecture.md) — layering (`core/` + `cli/` +
+  `tui/`), the TUI-first UI strategy, tool choices.
+- [docs/data-model.md](docs/data-model.md) — entities, the full SQL schema,
+  and the reasoning behind it.
+- [docs/non-goals.md](docs/non-goals.md) — features deliberately not built,
+  and why.
+
+## License
+
+[MIT](LICENSE)

tasko-0.0.1/pyproject.toml

@@ -0,0 +1,180 @@
+# ============================================================================
+#  Project metadata
+# ============================================================================
+[project]
+name = "tasko"
+version = "0.0.1"
+description = "Personal task manager"
+readme = "README.md"
+authors = [{ name = "pybass" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "rich~=15.0",
+    "textual~=8.2",
+]
+
+[project.urls]
+Repository = "https://github.com/pybass/tasko"
+Issues = "https://github.com/pybass/tasko/issues"
+
+[project.scripts]
+tasko = "tasko.cli.main:main"
+
+
+# ============================================================================
+#  Build system
+# ============================================================================
+# uv_build is pinned to a compatible range: the backend is an isolated build dependency that
+# uv.lock does not cover, so an open-ended requirement would let the same tag build differently
+# over time.
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+
+# ============================================================================
+#  Development dependencies — grouped by role (mirrors the tool sections below)
+# ============================================================================
+[dependency-groups]
+dev = [
+    # Linting & formatting
+    "ruff~=0.15.22",
+    # Type checking
+    "mypy~=2.3.0",
+    "ty~=0.0.60",
+    # Testing & coverage
+    "pytest~=9.1.1",
+    "pytest-asyncio~=1.4.0",
+    "pytest-cov~=7.1.0",
+    "pytest-xdist~=3.8.0",
+    # Security & vulnerability audit
+    "pip-audit~=2.10.1",
+    # Dependency hygiene — imports vs declared deps
+    "deptry~=0.25.1",
+    # Git pre-commit hooks
+    "pre-commit~=4.6.0",
+]
+
+
+# ============================================================================
+#  Ruff — linting & formatting
+# ============================================================================
+[tool.ruff]
+line-length = 130
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # --- Ecosystem / tool conflicts ---
+    "COM812",   # trailing-comma — handled by ruff formatter, must be off here
+    "ISC001",   # single-line-implicit-string-concat — conflicts with ruff formatter
+    "D203",     # one-blank-line-before-class — conflicts with D211
+    "D213",     # multi-line-summary-second-line — conflicts with D212
+
+    # --- Stylistic preferences ---
+    "A005",     # stdlib-module-shadowing — allowed when intentional
+    "PLC0414",  # useless-import-alias — `import x as x` is our explicit re-export marker
+    "RET503",   # implicit-return — explicit None returns are noisy
+    "G004",     # f-strings in logging — accepted
+
+    # --- flake8-pytest-style: opinionated rules only (bug-catchers stay on) ---
+    "PT001",    # fixture-incorrect-parentheses-style — cosmetic
+    "PT006",    # parametrize-names-wrong-type — cosmetic
+    "PT007",    # parametrize-values-wrong-type — cosmetic
+    "PT023",    # mark-incorrect-parentheses-style — cosmetic
+
+    # --- Categories that fight our coding style ---
+    "FIX",      # flake8-fixme — TODOs are fine; tracked elsewhere
+    "FBT",      # boolean-trap — too restrictive
+    "EM",       # error-message strings — inline messages accepted
+    "TRY003",   # raise-vanilla-args — too noisy
+    "C901",     # complex-structure — judgment call
+
+    # --- Soft pylint thresholds ---
+    "PLR0911",  # too-many-return-statements
+    "PLR0912",  # too-many-branches
+    "PLR0913",  # too-many-arguments
+    "PLR2004",  # magic-value-comparison
+
+    # --- TODO metadata (optional) ---
+    "TD002",    # missing-todo-author
+    "TD003",    # missing-todo-link
+
+    # --- Async edge case ---
+    "ASYNC109", # async-function-with-timeout — debatable, off
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN", "S"]  # tests skip type-annotation (ANN) and assert/security (S) rules
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true  # keep code examples in docstrings formatted like real code
+
+
+# ============================================================================
+#  Type checking — mypy (strict) + ty
+# ============================================================================
+[tool.mypy]
+python_version = "3.14"
+strict = true
+
+# Relax strictness on tests so pytest fixtures and untyped helpers don't fight you.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_decorators = false
+disallow_untyped_calls = false
+warn_unused_ignores = false
+
+[tool.ty.environment]
+python-version = "3.14"
+
+# Same intent as the mypy test override: silence test-only false positives.
+[[tool.ty.overrides]]
+include = ["tests/**"]
+[tool.ty.overrides.rules]
+possibly-missing-attribute = "ignore"
+invalid-assignment = "ignore"
+
+
+# ============================================================================
+#  Spell checking — codespell
+# ============================================================================
+[tool.codespell]
+skip = "uv.lock,.git,.venv,.mypy_cache,.ruff_cache,.pytest_cache,htmlcov"
+
+
+# ============================================================================
+#  Testing & coverage — pytest + coverage
+# ============================================================================
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config --import-mode=importlib"
+xfail_strict = true
+# `auto` lets async TUI tests (Textual Pilot) be plain `async def` functions.
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# Any warning raised in tests is a failure — deprecations surface at the commit that introduces
+# them, not at the upgrade that removes the API. Add targeted ignores below "error" when an
+# unfixable third-party warning appears, e.g.:
+#   "ignore:<message prefix>:DeprecationWarning:somepackage.*",
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

tasko-0.0.1/src/tasko/__init__.py

@@ -0,0 +1 @@
+"""Personal task manager."""

tasko-0.0.1/src/tasko/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI adapter."""

tasko-0.0.1/src/tasko/cli/main.py

@@ -0,0 +1,89 @@
+"""CLI adapter: quick capture and a quick look at the list. The TUI is the primary interface."""
+
+# ruff: noqa: T201 -- printing to stdout is this module's purpose: every command's user-facing
+# output goes through print(); the rule targets stray debug prints, which cannot exist here.
+
+import argparse
+import os
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from tasko.core.core import Core
+from tasko.core.errors import AppError
+from tasko.core.models import Priority, Status
+
+DATA_DIR_ENV_VAR = "TASKO_DATA_DIR"  # overrides the default data directory
+
+
+def main() -> None:
+    """Entry point: no subcommand launches the TUI; `add` and `list` serve capture and a quick look."""
+    args = _build_parser().parse_args()
+    core = Core(_resolve_db_path(args.data_dir))
+    try:
+        if args.command is None:
+            # Lazy import: quick capture (`tasko add`) must not pay the TUI framework's import cost.
+            from tasko.tui.app import TaskoApp  # noqa: PLC0415
+
+            TaskoApp(core).run()
+        elif args.command == "add":
+            _cmd_add(core, args)
+        else:
+            _cmd_list(core, args)
+    except AppError as e:
+        sys.exit(f"error: {e}")
+    finally:
+        core.close()
+
+
+def _resolve_db_path(data_dir: Path | None = None) -> Path:
+    """Path to the SQLite database file, resolving the data directory as CLI arg → env var → XDG default."""
+    if data_dir is None:
+        env = os.environ.get(DATA_DIR_ENV_VAR)
+        if env:
+            data_dir = Path(env)
+        else:
+            xdg_data_home = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+            data_dir = xdg_data_home / "tasko"
+    return data_dir / "tasko.db"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser with the `add` and `list` subcommands."""
+    parser = argparse.ArgumentParser(prog="tasko", description="Personal task manager.")
+    parser.add_argument("--version", action="version", version=version("tasko"))
+    parser.add_argument("--data-dir", type=Path, help=f"data directory (env: {DATA_DIR_ENV_VAR}; default: XDG data dir)")
+    subparsers = parser.add_subparsers(dest="command")
+
+    add = subparsers.add_parser("add", help="add a task")
+    add.add_argument("title", help="task title")
+    add.add_argument("-p", "--project", help="project name (default: the default project)")
+    add.add_argument("-b", "--body", help="longer description")
+    add.add_argument("--priority", type=Priority, choices=list(Priority), default=Priority.MEDIUM, help="task priority")
+
+    list_ = subparsers.add_parser("list", help="list tasks (open ones by default)")
+    list_.add_argument("-p", "--project", help="filter by project name")
+    list_.add_argument("-s", "--status", type=Status, choices=list(Status), help="filter by status")
+    list_.add_argument("--all", action="store_true", help="include done tasks")
+    return parser
+
+
+def _cmd_add(core: Core, args: argparse.Namespace) -> None:
+    """Create a task and confirm where it landed."""
+    project_id = core.get_project_by_name(args.project).id if args.project is not None else None
+    task = core.add_task(args.title, project_id=project_id, body=args.body, priority=args.priority)
+    print(f"Task #{task.id} created in project '{task.project_name}'.")
+
+
+def _cmd_list(core: Core, args: argparse.Namespace) -> None:
+    """Print tasks as an aligned table."""
+    project_id = core.get_project_by_name(args.project).id if args.project is not None else None
+    tasks = core.list_tasks(project_id=project_id, status=args.status, include_done=args.all)
+    if not tasks:
+        print("No tasks.")
+        return
+    header = ("ID", "Project", "Status", "Priority", "Title")
+    rows = [(str(t.id), t.project_name, t.status, t.priority, t.title) for t in tasks]
+    widths = [max(len(row[i]) for row in (header, *rows)) for i in range(len(header))]
+    for row in (header, *rows):
+        print("  ".join(cell.ljust(width) for cell, width in zip(row, widths, strict=True)).rstrip())

tasko-0.0.1/src/tasko/core/__init__.py

@@ -0,0 +1 @@
+"""Core business logic — the application without UI."""

tasko-0.0.1/src/tasko/core/core.py

@@ -0,0 +1,267 @@
+"""Application core: SQLite storage and business operations in one class."""
+
+import sqlite3
+import time
+from typing import TYPE_CHECKING
+
+from tasko.core.errors import AppError
+from tasko.core.migrations import MIGRATIONS
+from tasko.core.models import AppState, Priority, Project, Status, Task
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _now() -> int:
+    """Return the current unix time in whole seconds."""
+    return int(time.time())
+
+
+class Core:
+    """The application without UI: owns the SQLite connection and every operation on it.
+
+    Adapters (CLI, TUI) call these methods and show AppError messages to the user.
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        """Open the database (creating the file and its directory if needed) and migrate it."""
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(db_path)  # single shared connection
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA busy_timeout = 5000")
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._migrate()
+
+    def close(self) -> None:
+        """Close the connection."""
+        self._conn.close()
+
+    def _migrate(self) -> None:
+        """Apply pending migrations, tracked via PRAGMA user_version."""
+        version = int(self._conn.execute("PRAGMA user_version").fetchone()[0])
+        for number, script in enumerate(MIGRATIONS[version:], start=version + 1):
+            # The script and the version bump commit together: a crash mid-migration rolls back
+            # cleanly, so a migration is either fully applied and recorded, or not at all.
+            self._conn.executescript(f"BEGIN;\n{script}\nPRAGMA user_version = {number};\nCOMMIT;")
+
+    # --- Tasks ---
+
+    def add_task(
+        self, title: str, *, project_id: int | None = None, body: str | None = None, priority: Priority = Priority.MEDIUM
+    ) -> Task:
+        """Create a task and return it. Without a project id, it goes to the selected or default project."""
+        title = title.strip()
+        if not title:
+            raise AppError("Task title cannot be empty.")
+        if project_id is None:
+            state = self.app_state()
+            project_id = state.selected_project_id or state.default_project_id
+        try:
+            row = self._conn.execute(
+                """
+                INSERT INTO tasks (project_id, title, body, priority, created_at, updated_at)
+                VALUES (:project_id, :title, :body, :priority, :now, :now)
+                RETURNING id
+                """,
+                {"project_id": project_id, "title": title, "body": body, "priority": priority, "now": _now()},
+            ).fetchone()
+        except sqlite3.IntegrityError as e:  # foreign key: no such project
+            raise AppError(f"Project #{project_id} not found.") from e
+        self._conn.commit()
+        return self.get_task(int(row["id"]))
+
+    def get_task(self, task_id: int) -> Task:
+        """Return a task by id; raises AppError when it does not exist."""
+        row = self._conn.execute(
+            "SELECT t.*, p.name AS project_name FROM tasks t JOIN projects p ON p.id = t.project_id WHERE t.id = ?",
+            (task_id,),
+        ).fetchone()
+        if row is None:
+            raise AppError(f"Task #{task_id} not found.")
+        return Task.from_row(row)
+
+    def list_tasks(
+        self, *, project_id: int | None = None, status: Status | None = None, include_done: bool = False
+    ) -> list[Task]:
+        """Return tasks in working order, optionally filtered by project id and/or status; a None filter means "any".
+
+        Working order: doing first, then by priority, then recently updated; done tasks
+        sink to the bottom (recently finished first, since done_at == updated_at). They
+        are excluded by default; asking for status DONE explicitly implies them.
+        """
+        rows = self._conn.execute(
+            """
+            SELECT t.*, p.name AS project_name
+            FROM tasks t JOIN projects p ON p.id = t.project_id
+            WHERE (:project_id IS NULL OR t.project_id = :project_id)
+              AND (:status IS NULL OR t.status = :status)
+              AND (:include_done OR t.status != 'done')
+            ORDER BY t.status = 'done',
+                     t.status = 'doing' DESC,
+                     CASE t.priority WHEN 'high' THEN 0 WHEN 'medium' THEN 1 ELSE 2 END,
+                     t.updated_at DESC
+            """,
+            {"project_id": project_id, "status": status, "include_done": include_done or status is Status.DONE},
+        ).fetchall()
+        return [Task.from_row(row) for row in rows]
+
+    def project_task_counts(self) -> dict[int, tuple[int, int]]:
+        """Return {project_id: (open, total)} task counts; projects without tasks are absent."""
+        rows = self._conn.execute(
+            "SELECT project_id, sum(status != 'done') AS open, count(*) AS total FROM tasks GROUP BY project_id"
+        ).fetchall()
+        return {int(row["project_id"]): (int(row["open"]), int(row["total"])) for row in rows}
+
+    def set_status(self, task_id: int, status: Status) -> None:
+        """Move a task to the given status, maintaining done_at."""
+        now = _now()  # one timestamp for both columns: on completion done_at == updated_at
+        done_at = now if status is Status.DONE else None
+        cur = self._conn.execute(
+            "UPDATE tasks SET status = :status, done_at = :done_at, updated_at = :now WHERE id = :id",
+            {"status": status, "done_at": done_at, "now": now, "id": task_id},
+        )
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    def set_title(self, task_id: int, title: str) -> None:
+        """Rename a task; the new title must be non-empty."""
+        title = title.strip()
+        if not title:
+            raise AppError("Task title cannot be empty.")
+        cur = self._conn.execute(
+            "UPDATE tasks SET title = :title, updated_at = :now WHERE id = :id",
+            {"title": title, "now": _now(), "id": task_id},
+        )
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    def set_body(self, task_id: int, body: str | None) -> None:
+        """Replace a task's body; empty or whitespace-only text clears it."""
+        if body is not None:
+            body = body.strip() or None
+        cur = self._conn.execute(
+            "UPDATE tasks SET body = :body, updated_at = :now WHERE id = :id",
+            {"body": body, "now": _now(), "id": task_id},
+        )
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    def set_priority(self, task_id: int, priority: Priority) -> None:
+        """Change a task's priority."""
+        cur = self._conn.execute(
+            "UPDATE tasks SET priority = :priority, updated_at = :now WHERE id = :id",
+            {"priority": priority, "now": _now(), "id": task_id},
+        )
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    def set_project(self, task_id: int, project_id: int) -> None:
+        """Move a task to another project."""
+        try:
+            cur = self._conn.execute(
+                "UPDATE tasks SET project_id = :project_id, updated_at = :now WHERE id = :id",
+                {"project_id": project_id, "now": _now(), "id": task_id},
+            )
+        except sqlite3.IntegrityError as e:  # foreign key: no such project
+            raise AppError(f"Project #{project_id} not found.") from e
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    def delete_task(self, task_id: int) -> None:
+        """Delete a task permanently."""
+        cur = self._conn.execute("DELETE FROM tasks WHERE id = ?", (task_id,))
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Task #{task_id} not found.")
+
+    # --- Projects ---
+
+    def list_projects(self) -> list[Project]:
+        """Return all projects ordered by name."""
+        rows = self._conn.execute("SELECT id, name FROM projects ORDER BY name").fetchall()
+        return [Project(**dict(row)) for row in rows]
+
+    def get_project(self, project_id: int) -> Project:
+        """Return a project by id; raises AppError when it does not exist."""
+        row = self._conn.execute("SELECT id, name FROM projects WHERE id = ?", (project_id,)).fetchone()
+        if row is None:
+            raise AppError(f"Project #{project_id} not found.")
+        return Project(**dict(row))
+
+    def get_project_by_name(self, name: str) -> Project:
+        """Return a project by its unique name; raises AppError when it does not exist.
+
+        For adapters whose input addresses projects by name (the CLI); everything else uses ids.
+        """
+        row = self._conn.execute("SELECT id, name FROM projects WHERE name = ?", (name,)).fetchone()
+        if row is None:
+            raise AppError(f"Project '{name}' not found.")
+        return Project(**dict(row))
+
+    def create_project(self, name: str) -> None:
+        """Create a project with a unique non-empty name."""
+        name = name.strip()
+        if not name:
+            raise AppError("Project name cannot be empty.")
+        try:
+            self._conn.execute("INSERT INTO projects (name) VALUES (?)", (name,))
+        except sqlite3.IntegrityError as e:
+            raise AppError(f"Project '{name}' already exists.") from e
+        self._conn.commit()
+
+    def rename_project(self, project_id: int, new_name: str) -> None:
+        """Rename a project; the new name must be unique and non-empty."""
+        new_name = new_name.strip()
+        if not new_name:
+            raise AppError("Project name cannot be empty.")
+        try:
+            cur = self._conn.execute("UPDATE projects SET name = ? WHERE id = ?", (new_name, project_id))
+        except sqlite3.IntegrityError as e:
+            raise AppError(f"Project '{new_name}' already exists.") from e
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Project #{project_id} not found.")
+
+    def delete_project(self, project_id: int) -> None:
+        """Delete a project together with its tasks (ON DELETE CASCADE); the default project cannot be deleted."""
+        if project_id == self.app_state().default_project_id:
+            raise AppError("Cannot delete the default project; make another project the default first.")
+        cur = self._conn.execute("DELETE FROM projects WHERE id = ?", (project_id,))
+        self._conn.commit()
+        if cur.rowcount == 0:
+            raise AppError(f"Project #{project_id} not found.")
+
+    # --- App state ---
+
+    def app_state(self) -> AppState:
+        """Return the singleton application state."""
+        # Explicit columns, not *: the row also carries the singleton id, which AppState
+        # does not model and the dataclass constructor would reject.
+        row = self._conn.execute("SELECT default_project_id, selected_project_id, theme FROM app_state").fetchone()
+        if row is None:  # invariant broken — the database was edited outside the app; fail loudly
+            raise RuntimeError("database invariant violated: app_state row missing")
+        return AppState(**dict(row))
+
+    def set_selected_project(self, project_id: int | None) -> None:
+        """Set the persisted project filter; None means all projects."""
+        self._conn.execute("UPDATE app_state SET selected_project_id = ? WHERE id = 1", (project_id,))
+        self._conn.commit()
+
+    def set_theme(self, theme: str) -> None:
+        """Persist the UI theme choice."""
+        self._conn.execute("UPDATE app_state SET theme = ? WHERE id = 1", (theme,))
+        self._conn.commit()
+
+    def set_default_project(self, project_id: int) -> None:
+        """Make the given project the default target for quick capture."""
+        try:
+            self._conn.execute("UPDATE app_state SET default_project_id = ? WHERE id = 1", (project_id,))
+        except sqlite3.IntegrityError as e:  # foreign key: no such project
+            raise AppError(f"Project #{project_id} not found.") from e
+        self._conn.commit()

tasko-0.0.1/src/tasko/core/errors.py

@@ -0,0 +1,5 @@
+"""Application errors shared by all adapters."""
+
+
+class AppError(Exception):
+    """Business-rule violation or bad input; adapters show the message to the user."""