tasko 0.0.1__py3-none-any.whl

tasko/__init__.py

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

tasko/cli/__init__.py

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

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/core/__init__.py

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

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/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."""

tasko/core/migrations.py

@@ -0,0 +1,49 @@
+"""Database schema migrations, applied in order by Core."""
+
+# Schema v1 (see docs/data-model.md). IF NOT EXISTS / OR IGNORE predate the atomic runner
+# in Core._migrate and are harmless; new migrations don't need to be rerun-safe.
+_MIGRATION_V1 = """
+CREATE TABLE IF NOT EXISTS projects (
+    id   INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE CHECK (name <> '')
+) STRICT;
+
+-- Singleton app state. default_project_id is NOT NULL with no ON DELETE action, so a
+-- default project always exists and deleting it is refused by the database itself.
+-- selected_project_id is the persisted UI project filter; deleting that project resets it.
+-- theme has no CHECK: valid names come from the UI framework and change across its
+-- versions; the TUI validates the value and falls back to its default.
+CREATE TABLE IF NOT EXISTS app_state (
+    id                  INTEGER PRIMARY KEY CHECK (id = 1),
+    default_project_id  INTEGER NOT NULL REFERENCES projects(id),
+    selected_project_id INTEGER REFERENCES projects(id) ON DELETE SET NULL,
+    theme               TEXT NOT NULL DEFAULT 'textual-dark'
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS tasks (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    title      TEXT NOT NULL CHECK (title <> ''),
+    body       TEXT,
+    status     TEXT NOT NULL DEFAULT 'todo' CHECK (status IN ('todo', 'doing', 'done')),
+    priority   TEXT NOT NULL DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high')),
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    done_at    INTEGER,
+    CHECK ((status = 'done') = (done_at IS NOT NULL))
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+
+-- Readable listing for manual DB inspection; the application does not use it.
+CREATE VIEW IF NOT EXISTS tasks_v AS
+SELECT t.id, p.name AS project, t.status, t.priority, t.title, t.created_at, t.done_at
+FROM tasks t JOIN projects p ON p.id = t.project_id;
+
+-- Seed: a fresh database always starts with one project, which is the default.
+INSERT OR IGNORE INTO projects (name) VALUES ('inbox');
+INSERT OR IGNORE INTO app_state (id, default_project_id) SELECT 1, id FROM projects WHERE name = 'inbox';
+"""
+
+MIGRATIONS = (_MIGRATION_V1,)  # append-only; index+1 = PRAGMA user_version

tasko/core/models.py

@@ -0,0 +1,65 @@
+"""Domain models: projects, tasks, and their enums."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Self
+
+if TYPE_CHECKING:
+    import sqlite3
+
+
+class Status(StrEnum):
+    """Task lifecycle state; values match the TEXT stored in SQLite."""
+
+    TODO = "todo"
+    DOING = "doing"
+    DONE = "done"
+
+
+class Priority(StrEnum):
+    """Task priority; values match the TEXT stored in SQLite."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    """A project — the mandatory container every task belongs to."""
+
+    id: int  # stable identity; the display name can change freely
+    name: str  # unique, non-empty
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    """A single task, always scoped to a project."""
+
+    id: int  # stable id, never reused (AUTOINCREMENT)
+    project_id: int  # owning project
+    project_name: str  # owning project's name, joined in by core queries
+    title: str  # short summary, non-empty
+    body: str | None  # optional long description
+    status: Status  # current lifecycle state
+    priority: Priority  # low / medium / high
+    created_at: int  # unix seconds
+    updated_at: int  # unix seconds; equals created_at until the first modification
+    done_at: int | None  # unix seconds; set exactly when status is done
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> Self:
+        """Build a Task from a database row, coercing the TEXT status/priority into enums."""
+        data: dict[str, Any] = dict(row)
+        data["status"] = Status(data["status"])
+        data["priority"] = Priority(data["priority"])
+        return cls(**data)
+
+
+@dataclass(frozen=True, slots=True)
+class AppState:
+    """Singleton application state (the app_state table)."""
+
+    default_project_id: int  # quick-capture target when no project is selected
+    selected_project_id: int | None  # persisted project filter; None = all projects
+    theme: str  # persisted UI theme name (a Textual built-in theme)

tasko/tui/__init__.py

@@ -0,0 +1 @@
+"""TUI adapter — the primary interface."""

tasko/tui/app.py

@@ -0,0 +1,74 @@
+"""Textual application: a thin shell that mounts the main screen."""
+
+from typing import TYPE_CHECKING, ClassVar
+
+from textual.app import App
+
+from tasko.tui.screens.dialogs import HelpDialog
+from tasko.tui.screens.projects import ProjectsScreen
+from tasko.tui.screens.task_detail import TaskDetailScreen
+from tasko.tui.screens.task_list import TaskListScreen
+
+if TYPE_CHECKING:
+    from textual.binding import BindingType
+
+    from tasko.core.core import Core
+
+
+class TaskoApp(App[None]):
+    """Interactive TUI for managing tasks."""
+
+    TITLE = "tasko"  # terminal window/tab title
+
+    BINDINGS: ClassVar[list[BindingType]] = [("question_mark,i", "help", "Help")]
+
+    # One canvas: the screens share the table's background so content sits on a single surface.
+    # Deliberately not a bare `Screen` selector — that would also repaint the modal dialogs
+    # and kill their dimmed overlay.
+    CSS = """
+    TaskListScreen, TaskDetailScreen, ProjectsScreen {
+        background: $surface;
+    }
+    DataTable {
+        height: 1fr;
+    }
+    DataTable > .datatable--header {
+        background: transparent;
+        text-style: none;
+        color: $text-muted;
+    }
+    """
+
+    def __init__(self, core: Core) -> None:
+        """Wire the app to the shared core."""
+        super().__init__()
+        self._core = core  # application core, shared with the CLI
+
+    def action_help(self) -> None:
+        """Show the current screen's keys; screens opt in by defining a HELP_KEYS attribute."""
+        rows = getattr(self.screen, "HELP_KEYS", None)
+        if rows:
+            self.push_screen(HelpDialog(rows))
+
+    def on_mount(self) -> None:
+        """Restore the persisted theme and mount the main screen."""
+        theme = self._core.app_state().theme
+        if theme in self.available_themes:  # a stale name (theme gone from Textual) keeps the default
+            self.theme = theme
+        self.push_screen(TaskListScreen(self._core))
+
+    def watch_theme(self, theme: str) -> None:
+        """Persist every theme change (made via the ctrl+p command palette) across runs."""
+        self._core.set_theme(theme)
+
+    def on_app_focus(self) -> None:
+        """Reload the visible screen when the terminal regains focus.
+
+        This closes the quick-capture loop: `tasko add` from a shell, alt-tab back, the
+        list is fresh. Skipped while a dialog is on top — reloading under a modal could
+        fight the interaction in progress (r covers that case), and TaskDetailScreen.reload
+        pops the top screen when its task is gone, which must never hit a dialog.
+        """
+        screen = self.screen
+        if isinstance(screen, TaskListScreen | TaskDetailScreen | ProjectsScreen):
+            screen.reload()

tasko/tui/screens/__init__.py

@@ -0,0 +1 @@
+"""TUI screens."""