rook-cli 0.2.0__py3-none-any.whl

rook/persistence/migrations.py

@@ -0,0 +1,111 @@
+import sqlite3
+
+# Section 15.28: all four version-1 tables are created together in one
+# migration, since Routines/Routine Items are part of the same accepted
+# schema even though they remain unused until Phase 11.
+CURRENT_SCHEMA_VERSION = 1
+
+_SCHEMA_V1 = """
+CREATE TABLE app_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+CREATE TABLE tasks (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    text              TEXT NOT NULL CHECK (length(trim(text)) > 0),
+    state             TEXT NOT NULL
+                              CHECK (state IN ('open', 'migrated', 'completed', 'deleted')),
+    sort_order        INTEGER NOT NULL,
+    created_at        TEXT NOT NULL,
+    updated_at        TEXT NOT NULL,
+    state_changed_at  TEXT NOT NULL,
+    state_date        TEXT NOT NULL,
+    archived_date     TEXT,
+    archived_at       TEXT,
+    archive_order     INTEGER,
+
+    CHECK (
+        (archived_date IS NULL AND archived_at IS NULL AND archive_order IS NULL)
+        OR
+        (archived_date IS NOT NULL AND archived_at IS NOT NULL AND archive_order IS NOT NULL)
+    ),
+
+    CHECK (
+        archived_date IS NULL
+        OR state IN ('completed', 'deleted')
+    )
+);
+
+CREATE TABLE routines (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT NOT NULL CHECK (length(trim(name)) > 0),
+    sort_order  INTEGER NOT NULL,
+    is_deleted  INTEGER NOT NULL DEFAULT 0 CHECK (is_deleted IN (0, 1)),
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+);
+
+CREATE TABLE routine_items (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    routine_id  INTEGER NOT NULL,
+    text        TEXT NOT NULL CHECK (length(trim(text)) > 0),
+    sort_order  INTEGER NOT NULL,
+    is_deleted  INTEGER NOT NULL DEFAULT 0 CHECK (is_deleted IN (0, 1)),
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL,
+
+    FOREIGN KEY (routine_id)
+        REFERENCES routines(id)
+        ON DELETE CASCADE
+);
+
+CREATE INDEX ix_tasks_active_order
+ON tasks(archived_date, sort_order, id);
+
+CREATE INDEX ix_tasks_archive_date_order
+ON tasks(archived_date, archive_order, id);
+
+CREATE INDEX ix_tasks_rollover
+ON tasks(archived_date, state, state_date);
+
+CREATE INDEX ix_routines_order
+ON routines(sort_order, id);
+
+CREATE INDEX ix_routine_items_order
+ON routine_items(routine_id, is_deleted, sort_order, id);
+
+CREATE UNIQUE INDEX ux_routines_active_name
+ON routines(lower(trim(name)))
+WHERE is_deleted = 0;
+"""
+
+
+class UnsupportedSchemaVersionError(RuntimeError):
+    """Raised when the database's schema is newer than this build understands."""
+
+    def __init__(self, found_version: int) -> None:
+        super().__init__(
+            f"This database uses schema version {found_version}, but this version "
+            f"of Rook only understands up to version {CURRENT_SCHEMA_VERSION}. "
+            "The database was left untouched."
+        )
+        self.found_version = found_version
+
+
+def migrate(connection: sqlite3.Connection) -> None:
+    """Bring the database up to CURRENT_SCHEMA_VERSION (Section 15.5).
+
+    Safe to call every startup: a database already at the current version
+    is left untouched. A database from a newer, not-yet-understood version
+    is rejected rather than silently used or altered.
+    """
+    current_version = connection.execute("PRAGMA user_version").fetchone()[0]
+
+    if current_version > CURRENT_SCHEMA_VERSION:
+        raise UnsupportedSchemaVersionError(current_version)
+
+    if current_version == 0:
+        connection.executescript(_SCHEMA_V1)
+        connection.execute(f"PRAGMA user_version = {CURRENT_SCHEMA_VERSION};")
+        connection.commit()

rook/persistence/tasks.py

@@ -0,0 +1,185 @@
+import sqlite3
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from rook.domain.tasks import Task, TaskState
+
+
+@dataclass(frozen=True, slots=True)
+class TaskSnapshot:
+    """A permanently-removed Task's row exactly as it existed just before
+    removal (Section 8.9), kept only long enough for a same-session undo
+    to restore it precisely - including its position, since a restored
+    Task must reappear in its original relative order.
+    """
+
+    id: int
+    text: str
+    state: TaskState
+    sort_order: int
+    created_at: str
+    updated_at: str
+    state_changed_at: str
+    state_date: str
+
+
+class TaskRepository:
+    """SQL access for active Tasks (Section 15.22). No Textual imports."""
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        self._connection = connection
+
+    def list_active_tasks(self) -> list[Task]:
+        rows = self._connection.execute(
+            """
+            SELECT id, text, state
+            FROM tasks
+            WHERE archived_date IS NULL
+            ORDER BY sort_order ASC, id ASC
+            """
+        ).fetchall()
+        return [_row_to_task(row) for row in rows]
+
+    def create_task(self, text: str, *, now: datetime, local_date: date) -> Task:
+        timestamp = now.isoformat()
+        with self._connection:
+            next_order = self._connection.execute(
+                "SELECT COALESCE(MAX(sort_order), 0) + 1 FROM tasks WHERE archived_date IS NULL"
+            ).fetchone()[0]
+            cursor = self._connection.execute(
+                """
+                INSERT INTO tasks (
+                    text, state, sort_order, created_at, updated_at,
+                    state_changed_at, state_date
+                ) VALUES (?, 'open', ?, ?, ?, ?, ?)
+                """,
+                (text, next_order, timestamp, timestamp, timestamp, local_date.isoformat()),
+            )
+            task_id = cursor.lastrowid
+            assert task_id is not None, "INSERT must assign a row id"
+        return Task(id=task_id, text=text, state=TaskState.OPEN)
+
+    def update_task_text(self, task_id: int, text: str, *, now: datetime) -> Task:
+        timestamp = now.isoformat()
+        with self._connection:
+            cursor = self._connection.execute(
+                """
+                UPDATE tasks
+                SET text = ?, updated_at = ?
+                WHERE id = ? AND archived_date IS NULL
+                """,
+                (text, timestamp, task_id),
+            )
+            if cursor.rowcount != 1:
+                raise LookupError(f"No active task with id {task_id}")
+            row = self._connection.execute(
+                "SELECT id, text, state FROM tasks WHERE id = ?", (task_id,)
+            ).fetchone()
+        return _row_to_task(row)
+
+    def set_task_state(
+        self, task_id: int, state: TaskState, *, now: datetime, local_date: date
+    ) -> Task:
+        """Section 15.9: state_date is stamped at the moment of the
+        transition, not derived later, so historical Archive dates stay
+        stable even if the user's time zone changes afterward."""
+        timestamp = now.isoformat()
+        with self._connection:
+            cursor = self._connection.execute(
+                """
+                UPDATE tasks
+                SET state = ?, updated_at = ?, state_changed_at = ?, state_date = ?
+                WHERE id = ? AND archived_date IS NULL
+                """,
+                (state.value, timestamp, timestamp, local_date.isoformat(), task_id),
+            )
+            if cursor.rowcount != 1:
+                raise LookupError(f"No active task with id {task_id}")
+            row = self._connection.execute(
+                "SELECT id, text, state FROM tasks WHERE id = ?", (task_id,)
+            ).fetchone()
+        return _row_to_task(row)
+
+    def delete_active_task(self, task_id: int) -> TaskSnapshot:
+        """Second-stage delete (Section 15.14): permanently remove a
+        Soft-Deleted Task. Returns the row exactly as it existed
+        immediately before removal, so a same-session undo (Phase 7) can
+        restore it precisely.
+        """
+        with self._connection:
+            row = self._connection.execute(
+                """
+                SELECT id, text, state, sort_order, created_at, updated_at,
+                       state_changed_at, state_date
+                FROM tasks
+                WHERE id = ? AND archived_date IS NULL
+                """,
+                (task_id,),
+            ).fetchone()
+            if row is None:
+                raise LookupError(f"No active task with id {task_id}")
+            removed = _row_to_snapshot(row)
+
+            cursor = self._connection.execute(
+                "DELETE FROM tasks WHERE id = ? AND archived_date IS NULL AND state = 'deleted'",
+                (task_id,),
+            )
+            if cursor.rowcount != 1:
+                raise LookupError(f"Task {task_id} is not eligible for permanent removal")
+        return removed
+
+    def restore_task(self, snapshot: TaskSnapshot) -> Task:
+        """Undo of a permanent removal: reinsert the row exactly as
+        captured. The restored Task is still Deleted (Section 8.9) -
+        undoing a removal does not reopen the Task."""
+        with self._connection:
+            self._connection.execute(
+                """
+                INSERT INTO tasks (
+                    id, text, state, sort_order, created_at, updated_at,
+                    state_changed_at, state_date
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    snapshot.id,
+                    snapshot.text,
+                    snapshot.state.value,
+                    snapshot.sort_order,
+                    snapshot.created_at,
+                    snapshot.updated_at,
+                    snapshot.state_changed_at,
+                    snapshot.state_date,
+                ),
+            )
+        return Task(id=snapshot.id, text=snapshot.text, state=snapshot.state)
+
+    def delete_task_by_id(self, task_id: int) -> None:
+        """Unconditional removal used only to undo a same-session Task
+        creation (Section 15.19 DeleteCreatedTask). Safe without a state
+        guard because single-level undo guarantees no other mutation has
+        touched this Task since it was created - otherwise that later
+        mutation would have replaced this undo record first.
+        """
+        with self._connection:
+            cursor = self._connection.execute(
+                "DELETE FROM tasks WHERE id = ? AND archived_date IS NULL", (task_id,)
+            )
+            if cursor.rowcount != 1:
+                raise LookupError(f"No active task with id {task_id}")
+
+
+def _row_to_task(row: sqlite3.Row) -> Task:
+    return Task(id=row["id"], text=row["text"], state=TaskState(row["state"]))
+
+
+def _row_to_snapshot(row: sqlite3.Row) -> TaskSnapshot:
+    return TaskSnapshot(
+        id=row["id"],
+        text=row["text"],
+        state=TaskState(row["state"]),
+        sort_order=row["sort_order"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+        state_changed_at=row["state_changed_at"],
+        state_date=row["state_date"],
+    )

rook/services/rollover.py

@@ -0,0 +1,94 @@
+import sqlite3
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from rook.persistence.metadata import MetadataRepository
+
+
+@dataclass(frozen=True, slots=True)
+class RolloverResult:
+    """Summary sufficient for the screen to decide whether to refresh
+    (Section 16.17)."""
+
+    changed: bool
+
+
+class RolloverService:
+    """Owns Day Rollover (Section 5.2, 15.12, 16.17).
+
+    Unlike ordinary Task mutations, archiving, renumbering, and updating
+    `last_processed_date` must commit as a single atomic transaction, so
+    this service holds the raw connection directly rather than composing
+    calls to TaskRepository/MetadataRepository, each of which would commit
+    independently and break that guarantee.
+    """
+
+    def __init__(
+        self,
+        connection: sqlite3.Connection,
+        metadata_repository: MetadataRepository,
+        *,
+        today_provider: Callable[[], date] = date.today,
+        now_provider: Callable[[], datetime] = datetime.now,
+    ) -> None:
+        self._connection = connection
+        self._metadata = metadata_repository
+        self._today_provider = today_provider
+        self._now_provider = now_provider
+
+    def roll_forward_if_needed(self) -> RolloverResult:
+        today = self._today_provider()
+        last_processed = self._metadata.get_last_processed_date()
+
+        if last_processed is None:
+            # First launch ever: nothing exists to archive yet.
+            self._metadata.set_last_processed_date(today)
+            return RolloverResult(changed=False)
+
+        # Section 18.14: only roll forward, never backward. This single
+        # comparison also handles multiple missed days (Section 18.13)
+        # without any per-day loop - archive eligibility below is judged
+        # against each Task's own state_date, not against "yesterday".
+        if today <= last_processed:
+            return RolloverResult(changed=False)
+
+        timestamp = self._now_provider().isoformat()
+        with self._connection:
+            self._connection.execute(
+                """
+                UPDATE tasks
+                SET archived_date = state_date, archived_at = ?, archive_order = sort_order
+                WHERE archived_date IS NULL
+                  AND state IN ('completed', 'deleted')
+                  AND state_date < ?
+                """,
+                (timestamp, today.isoformat()),
+            )
+
+            # Section 15.12 step 3: renumber remaining active Tasks so
+            # sort_order stays contiguous, preserving relative order.
+            remaining_ids = [
+                row["id"]
+                for row in self._connection.execute(
+                    """
+                    SELECT id FROM tasks
+                    WHERE archived_date IS NULL
+                    ORDER BY sort_order ASC, id ASC
+                    """
+                ).fetchall()
+            ]
+            for new_order, task_id in enumerate(remaining_ids, start=1):
+                self._connection.execute(
+                    "UPDATE tasks SET sort_order = ? WHERE id = ?", (new_order, task_id)
+                )
+
+            self._connection.execute(
+                """
+                INSERT INTO app_meta (key, value) VALUES ('last_processed_date', ?)
+                ON CONFLICT(key) DO UPDATE SET value = excluded.value
+                """,
+                (today.isoformat(),),
+            )
+
+        return RolloverResult(changed=True)

rook/services/tasks.py

@@ -0,0 +1,85 @@
+import sqlite3
+from collections.abc import Callable
+from datetime import date, datetime
+
+from rook.domain.tasks import Task, TaskState
+from rook.persistence.tasks import TaskRepository, TaskSnapshot
+
+
+class PersistenceError(Exception):
+    """Raised when a Task mutation could not be durably saved.
+
+    The presentation layer catches this and shows a status message
+    (Section 10.16) rather than pretending the mutation succeeded
+    (FR-104).
+    """
+
+
+class TaskService:
+    """Coordinates Task mutations for the presentation layer.
+
+    Translates low-level sqlite3 failures into PersistenceError so
+    widgets never need to know about sqlite3 directly.
+    """
+
+    def __init__(
+        self,
+        repository: TaskRepository,
+        *,
+        now_provider: Callable[[], datetime] = datetime.now,
+        today_provider: Callable[[], date] = date.today,
+    ) -> None:
+        self._repository = repository
+        self._now_provider = now_provider
+        self._today_provider = today_provider
+
+    def list_active_tasks(self) -> list[Task]:
+        try:
+            return self._repository.list_active_tasks()
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def create_task(self, text: str) -> Task:
+        try:
+            return self._repository.create_task(
+                text, now=self._now_provider(), local_date=self._today_provider()
+            )
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def update_task_text(self, task_id: int, text: str) -> Task:
+        try:
+            return self._repository.update_task_text(task_id, text, now=self._now_provider())
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def set_task_state(self, task_id: int, state: TaskState) -> Task:
+        try:
+            return self._repository.set_task_state(
+                task_id, state, now=self._now_provider(), local_date=self._today_provider()
+            )
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def delete_task(self, task_id: int) -> TaskSnapshot:
+        """Permanently remove a Soft-Deleted Task, returning its last
+        known row so a same-session undo can restore it precisely."""
+        try:
+            return self._repository.delete_active_task(task_id)
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def restore_task(self, snapshot: TaskSnapshot) -> Task:
+        """Undo a permanent removal (Phase 7)."""
+        try:
+            return self._repository.restore_task(snapshot)
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error
+
+    def discard_created_task(self, task_id: int) -> None:
+        """Undo a Task creation (Phase 7). Distinct from delete_task
+        because a just-created Task is Open, not Deleted."""
+        try:
+            self._repository.delete_task_by_id(task_id)
+        except sqlite3.Error as error:
+            raise PersistenceError(str(error)) from error

rook/services/undo.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+
+from rook.domain.tasks import TaskState
+from rook.persistence.tasks import TaskSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class DeleteCreatedTask:
+    """Undo a Task creation: the Task is Open and untouched since single-
+    level undo guarantees nothing else has mutated it since (Section 15.19).
+    """
+
+    task_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class RestoreTaskText:
+    """Undo a text edit."""
+
+    task_id: int
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class RestoreTaskState:
+    """Undo a state change (`x`, `>`, or a first `d`)."""
+
+    task_id: int
+    state: TaskState
+
+
+@dataclass(frozen=True, slots=True)
+class RestoreTaskSnapshot:
+    """Undo a permanent removal (second `d`), reinserting at its original
+    list position."""
+
+    index: int
+    snapshot: TaskSnapshot
+
+
+UndoCommand = DeleteCreatedTask | RestoreTaskText | RestoreTaskState | RestoreTaskSnapshot
+
+
+class UndoManager:
+    """Holds at most one inverse command for the current session (Section
+    16.20). Pure in-memory bookkeeping - no database connection, no
+    widgets, no asyncio. The presentation layer decides how to apply each
+    command type and through which service calls.
+    """
+
+    def __init__(self) -> None:
+        self._command: UndoCommand | None = None
+
+    def record(self, command: UndoCommand) -> None:
+        self._command = command
+
+    def clear(self) -> None:
+        self._command = None
+
+    @property
+    def has_undo(self) -> bool:
+        return self._command is not None
+
+    def take(self) -> UndoCommand | None:
+        """Remove and return the pending command, if any.
+
+        Version 1 has no redo, so taking a command always clears the slot
+        - if applying it fails, the caller may choose to record() it again.
+        """
+        command = self._command
+        self._command = None
+        return command

rook/symbols.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from rook.domain.tasks import TaskState
+
+# Column layout is fixed (Section 11.3): selection indicator, space, state
+# symbol, space, then task text. The reserved selection column plus its
+# following space is 2 characters; the state symbol plus its following
+# space is another 2 characters.
+PREFIX_WIDTH = 4
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolSet:
+    open: str
+    completed: str
+    migrated: str
+    selected: str
+    deleted_fallback: str
+
+
+PREFERRED = SymbolSet(open="•", completed="×", migrated=">", selected="❯", deleted_fallback="~")
+SAFE = SymbolSet(open="*", completed="x", migrated=">", selected=">", deleted_fallback="~")
+
+
+def state_symbol(state: TaskState, symbols: SymbolSet, *, safe_mode: bool) -> str:
+    """The glyph shown in the state-symbol column for a given Task state.
+
+    A Deleted Task's preferred display retains its normal open bullet and
+    relies on strikethrough styling to signal deletion (Section 11.5); the
+    fallback instead replaces the symbol outright with ``deleted_fallback``.
+    """
+    if state is TaskState.DELETED:
+        return symbols.deleted_fallback if safe_mode else symbols.open
+    if state is TaskState.OPEN:
+        return symbols.open
+    if state is TaskState.MIGRATED:
+        return symbols.migrated
+    if state is TaskState.COMPLETED:
+        return symbols.completed
+    raise AssertionError(f"Unhandled task state: {state!r}")