tsk-todo 0.1.0__py3-none-any.whl

tsk/cli.py

@@ -0,0 +1,202 @@
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import replace
+from datetime import UTC, datetime
+from typing import TextIO
+
+from tsk.dates import describe
+from tsk.model import Task, TaskNotFound, Tasks
+from tsk.parse import (
+    Add,
+    Attributes,
+    Command,
+    Done,
+    Edit,
+    Help,
+    Listing,
+    Note,
+    ParseError,
+    Remove,
+    Show,
+    Version,
+    parse,
+)
+from tsk.query import Query
+from tsk.render import Renderer, ink_for
+from tsk.store import Store, StoreError, default_path
+
+HELP = """tsk, a small task manager
+
+usage
+  tsk                        list pending tasks
+  tsk add <text> [attrs]     add a task
+  tsk done <id>...           complete tasks
+  tsk rm <id>...             delete tasks
+  tsk edit <id> <attrs>      change a task
+  tsk note <id> <text>       attach a note
+  tsk show <id>              show one task in full
+  tsk list [filters]         list tasks
+
+attributes
+  @project                   set the project, bare @ clears it
+  +tag                       add a tag
+  -tag                       remove a tag, when editing
+  due:<when>                 set a due date, bare due: clears it
+  p:h|m|l                    set priority
+  every:<repeat>             reschedule on completion
+
+filters
+  @project +tag -tag         match on project and tags
+  due:<when>                 due on or before a date
+  overdue                    past due
+  done                       completed tasks
+  all                        every task
+  <word>                     search descriptions and notes
+
+when
+  today, tomorrow, yesterday
+  monday to sunday, or mon to sun
+  3d, 2w, 1m, 1y
+  eow, eom, eoy
+  2026-08-01
+
+repeat
+  daily, weekdays, weekly, monthly, yearly
+
+examples
+  tsk add water the plants @home +garden due:tomorrow every:weekly
+  tsk add fix the login bug @work p:h due:friday
+  tsk +garden
+  tsk done 3
+  tsk edit 3 due: p:l"""
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class App:
+    def __init__(
+        self,
+        store: Store,
+        out: TextIO,
+        err: TextIO,
+        now: Callable[[], datetime] = _utcnow,
+    ) -> None:
+        self._store = store
+        self._out = out
+        self._err = err
+        self._clock = now
+        self._today = now().astimezone().date()
+        self._renderer = Renderer(ink_for(out), today=self._today)
+
+    def run(self, argv: Sequence[str]) -> int:
+        try:
+            return self._execute(parse(argv, today=self._today))
+        except (ParseError, StoreError) as error:
+            return self._fail(str(error))
+        except TaskNotFound as error:
+            return self._fail(f"no task with id {error.args[0]}")
+
+    def _execute(self, command: Command) -> int:
+        match command:
+            case Help():
+                return self._emit(HELP)
+            case Version():
+                return self._emit(f"tsk {_installed_version()}")
+            case Listing(query):
+                return self._list(query)
+            case Show(task_id):
+                return self._show(task_id)
+            case Add(attributes):
+                return self._add(attributes)
+            case Done(ids):
+                return self._done(ids)
+            case Remove(ids):
+                return self._remove(ids)
+            case Edit(task_id, attributes):
+                return self._edit(task_id, attributes)
+            case Note(task_id, text):
+                return self._note(task_id, text)
+
+    def _list(self, query: Query) -> int:
+        tasks = self._store.read()
+        found = sorted(
+            (task for task in tasks if query.matches(task, self._today)),
+            key=Task.ordering,
+        )
+        return self._emit(self._renderer.table(found))
+
+    def _show(self, task_id: int) -> int:
+        return self._emit(self._renderer.detail(self._store.read().find(task_id)))
+
+    def _add(self, attributes: Attributes) -> int:
+        tasks = self._store.read()
+        blank = Task(id=tasks.next_id(), description="", created=self._clock())
+        task = attributes.apply(blank)
+        tasks.append(task)
+        self._store.write(tasks)
+        return self._emit(f"added {task.id}: {task.description}")
+
+    def _done(self, ids: Sequence[int]) -> int:
+        tasks = self._store.read()
+        lines: list[str] = []
+        for task_id in ids:
+            done, successor = tasks.find(task_id).complete(
+                now=self._clock(), today=self._today
+            )
+            tasks.update(done)
+            lines.append(f"done {done.id}: {done.description}")
+            if successor is not None:
+                lines.append(self._reschedule(successor, tasks))
+        self._store.write(tasks)
+        return self._emit("\n".join(lines))
+
+    def _reschedule(self, successor: Task, tasks: Tasks) -> str:
+        scheduled = replace(successor, id=tasks.next_id())
+        tasks.append(scheduled)
+        when = describe(scheduled.due, self._today) if scheduled.due else "no date"
+        return f"  repeats as {scheduled.id}, due {when}"
+
+    def _remove(self, ids: Sequence[int]) -> int:
+        tasks = self._store.read()
+        lines: list[str] = []
+        for task_id in ids:
+            task = tasks.find(task_id)
+            tasks.discard(task_id)
+            lines.append(f"removed {task.id}: {task.description}")
+        self._store.write(tasks)
+        return self._emit("\n".join(lines))
+
+    def _edit(self, task_id: int, attributes: Attributes) -> int:
+        tasks = self._store.read()
+        task = attributes.apply(tasks.find(task_id))
+        tasks.update(task)
+        self._store.write(tasks)
+        return self._emit(f"updated {task.id}: {task.description}")
+
+    def _note(self, task_id: int, text: str) -> int:
+        tasks = self._store.read()
+        task = tasks.find(task_id).annotate(text)
+        tasks.update(task)
+        self._store.write(tasks)
+        return self._emit(f"noted on {task.id}: {task.description}")
+
+    def _emit(self, message: str) -> int:
+        print(message, file=self._out)
+        return 0
+
+    def _fail(self, message: str) -> int:
+        print(f"tsk: {message}", file=self._err)
+        return 1
+
+
+def _installed_version() -> str:
+    from importlib.metadata import version
+
+    return version("tsk-todo")
+
+
+def main() -> int:
+    app = App(Store(default_path()), out=sys.stdout, err=sys.stderr)
+    return app.run(sys.argv[1:])

tsk/dates.py

@@ -0,0 +1,122 @@
+import calendar
+import re
+from collections.abc import Callable
+from datetime import date, timedelta
+
+_ISO_DATE = re.compile(r"\d{4}-\d{2}-\d{2}\Z")
+_OFFSET = re.compile(r"(\d+)([dwmy])\Z")
+_WEEKDAY_NAMES = (
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+)
+_DAYS_PER_YEAR = 365
+_SATURDAY = 5
+
+
+class DateError(ValueError):
+    """Raised when a phrase cannot be read as a date."""
+
+
+def parse_date(phrase: str, today: date) -> date:
+    text = phrase.strip().lower()
+    for resolve in (_from_iso, _from_name, _from_weekday, _from_offset):
+        when = resolve(text, today)
+        if when is not None:
+            return when
+    raise DateError(f"not a date: {phrase!r}")
+
+
+def describe(when: date, today: date) -> str:
+    days = (when - today).days
+    if days == 0:
+        return "today"
+    if days == 1:
+        return "tomorrow"
+    if days == -1:
+        return "yesterday"
+    if abs(days) > _DAYS_PER_YEAR:
+        return when.isoformat()
+    span = _span(abs(days))
+    return f"in {span}" if days > 0 else f"{span} ago"
+
+
+def _span(days: int) -> str:
+    if days < 7:
+        return _counted(days, "day")
+    if days < 30:
+        return _counted(days // 7, "week")
+    return _counted(days // 30, "month")
+
+
+def _counted(count: int, unit: str) -> str:
+    return f"{count} {unit}" if count == 1 else f"{count} {unit}s"
+
+
+def _from_iso(text: str, today: date) -> date | None:
+    if not _ISO_DATE.match(text):
+        return None
+    try:
+        return date.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def _from_name(text: str, today: date) -> date | None:
+    resolve = _NAMED.get(text)
+    return resolve(today) if resolve else None
+
+
+def _from_weekday(text: str, today: date) -> date | None:
+    for index, name in enumerate(_WEEKDAY_NAMES):
+        if text in (name, name[:3]):
+            return today + timedelta(days=(index - today.weekday()) % 7 or 7)
+    return None
+
+
+def _from_offset(text: str, today: date) -> date | None:
+    match = _OFFSET.match(text)
+    if match is None:
+        return None
+    count, unit = int(match[1]), match[2]
+    if unit == "d":
+        return today + timedelta(days=count)
+    if unit == "w":
+        return today + timedelta(weeks=count)
+    return add_months(today, count * 12 if unit == "y" else count)
+
+
+def add_months(start: date, months: int) -> date:
+    month_index = start.month - 1 + months
+    year = start.year + month_index // 12
+    month = month_index % 12 + 1
+    return date(year, month, min(start.day, calendar.monthrange(year, month)[1]))
+
+
+def _end_of_week(today: date) -> date:
+    return today + timedelta(days=6 - today.weekday())
+
+
+def _end_of_month(today: date) -> date:
+    return today.replace(day=calendar.monthrange(today.year, today.month)[1])
+
+
+def next_weekday(after: date) -> date:
+    when = after + timedelta(days=1)
+    while when.weekday() >= _SATURDAY:
+        when += timedelta(days=1)
+    return when
+
+
+_NAMED: dict[str, Callable[[date], date]] = {
+    "today": lambda today: today,
+    "tomorrow": lambda today: today + timedelta(days=1),
+    "yesterday": lambda today: today - timedelta(days=1),
+    "eow": _end_of_week,
+    "eom": _end_of_month,
+    "eoy": lambda today: today.replace(month=12, day=31),
+}

tsk/model.py

@@ -0,0 +1,137 @@
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass, field, replace
+from datetime import UTC, date, datetime, timedelta
+from enum import StrEnum
+
+from tsk.dates import add_months, next_weekday
+
+
+class Status(StrEnum):
+    PENDING = "pending"
+    DONE = "done"
+
+
+class Priority(StrEnum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+    @property
+    def rank(self) -> int:
+        return list(Priority).index(self)
+
+
+class Recurrence(StrEnum):
+    DAILY = "daily"
+    WEEKDAYS = "weekdays"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    YEARLY = "yearly"
+
+    def after(self, when: date) -> date:
+        return _ADVANCE[self](when)
+
+    def upcoming(self, after: date, today: date) -> date:
+        when = self.after(after)
+        while when <= today:
+            when = self.after(when)
+        return when
+
+
+_ADVANCE: dict[Recurrence, Callable[[date], date]] = {
+    Recurrence.DAILY: lambda when: when + timedelta(days=1),
+    Recurrence.WEEKDAYS: next_weekday,
+    Recurrence.WEEKLY: lambda when: when + timedelta(weeks=1),
+    Recurrence.MONTHLY: lambda when: add_months(when, 1),
+    Recurrence.YEARLY: lambda when: add_months(when, 12),
+}
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    id: int
+    description: str
+    status: Status = Status.PENDING
+    project: str | None = None
+    tags: frozenset[str] = frozenset()
+    due: date | None = None
+    priority: Priority | None = None
+    every: Recurrence | None = None
+    notes: tuple[str, ...] = ()
+    created: datetime = field(default_factory=_utcnow)
+    completed: datetime | None = None
+
+    def complete(self, now: datetime, today: date) -> tuple["Task", "Task | None"]:
+        done = replace(self, status=Status.DONE, completed=now)
+        return done, self._successor(now, today)
+
+    def annotate(self, note: str) -> "Task":
+        return replace(self, notes=(*self.notes, note))
+
+    def is_overdue(self, today: date) -> bool:
+        return (
+            self.status is Status.PENDING and self.due is not None and self.due < today
+        )
+
+    def ordering(self) -> tuple[date, int, int]:
+        return (
+            self.due or date.max,
+            self.priority.rank if self.priority else len(Priority),
+            self.id,
+        )
+
+    def _successor(self, now: datetime, today: date) -> "Task | None":
+        if self.every is None or self.due is None:
+            return None
+        return replace(
+            self,
+            due=self.every.upcoming(self.due, today),
+            notes=(),
+            created=now,
+            completed=None,
+        )
+
+
+class TaskNotFound(LookupError):
+    """Raised when no task carries the given id."""
+
+
+class Tasks:
+    def __init__(self, items: Iterable[Task] = (), issued: int = 0) -> None:
+        self._items = list(items)
+        self._issued = max([issued, *(task.id for task in self._items)])
+
+    def __iter__(self) -> Iterator[Task]:
+        return iter(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    @property
+    def issued(self) -> int:
+        return self._issued
+
+    def next_id(self) -> int:
+        self._issued += 1
+        return self._issued
+
+    def find(self, task_id: int) -> Task:
+        for task in self._items:
+            if task.id == task_id:
+                return task
+        raise TaskNotFound(task_id)
+
+    def append(self, task: Task) -> None:
+        self._items.append(task)
+
+    def update(self, task: Task) -> None:
+        self.find(task.id)
+        self._items = [task if item.id == task.id else item for item in self._items]
+
+    def discard(self, task_id: int) -> None:
+        self.find(task_id)
+        self._items = [item for item in self._items if item.id != task_id]

tsk/parse.py

@@ -0,0 +1,272 @@
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import date
+from typing import Any
+
+from tsk.dates import DateError, parse_date
+from tsk.model import Priority, Recurrence, Status, Task
+from tsk.query import Query
+
+
+class ParseError(ValueError):
+    """Raised when a command line cannot be understood."""
+
+
+@dataclass(frozen=True)
+class Attributes:
+    words: tuple[str, ...] = ()
+    changes: Mapping[str, Any] = field(default_factory=dict)
+    add_tags: frozenset[str] = frozenset()
+    remove_tags: frozenset[str] = frozenset()
+
+    def apply(self, task: Task) -> Task:
+        updates = dict(self.changes)
+        if self.words:
+            updates["description"] = " ".join(self.words)
+        tags = (task.tags | self.add_tags) - self.remove_tags
+        return replace(task, tags=tags, **updates)
+
+
+@dataclass(frozen=True)
+class Add:
+    attributes: Attributes
+
+
+@dataclass(frozen=True)
+class Listing:
+    query: Query
+
+
+@dataclass(frozen=True)
+class Done:
+    ids: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Remove:
+    ids: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Edit:
+    id: int
+    attributes: Attributes
+
+
+@dataclass(frozen=True)
+class Note:
+    id: int
+    text: str
+
+
+@dataclass(frozen=True)
+class Show:
+    id: int
+
+
+@dataclass(frozen=True)
+class Help:
+    pass
+
+
+@dataclass(frozen=True)
+class Version:
+    pass
+
+
+Command = Add | Listing | Done | Remove | Edit | Note | Show | Help | Version
+
+_HELP_WORDS = frozenset({"help", "--help", "-h"})
+_VERSION_WORDS = frozenset({"version", "--version"})
+
+
+def parse(argv: Sequence[str], today: date) -> Command:
+    if not argv:
+        return Listing(Query())
+    head, *rest = argv
+    if head in _HELP_WORDS:
+        return Help()
+    if head in _VERSION_WORDS:
+        return Version()
+    verb = _VERBS.get(head)
+    if verb is not None:
+        return verb(rest, today)
+    if len(argv) == 1 and _is_id(head):
+        return Show(int(head))
+    return _listing(argv, today)
+
+
+def _add(tokens: Sequence[str], today: date) -> Command:
+    attributes = _attributes(tokens, today, removals=False)
+    if not attributes.words:
+        raise ParseError("add needs a description")
+    return Add(attributes)
+
+
+def _done(tokens: Sequence[str], today: date) -> Command:
+    return Done(_ids(tokens, "done"))
+
+
+def _remove(tokens: Sequence[str], today: date) -> Command:
+    return Remove(_ids(tokens, "rm"))
+
+
+def _edit(tokens: Sequence[str], today: date) -> Command:
+    task_id, rest = _leading_id(tokens, "edit")
+    if not rest:
+        raise ParseError("edit needs something to change")
+    return Edit(task_id, _attributes(rest, today, removals=True))
+
+
+def _note(tokens: Sequence[str], today: date) -> Command:
+    task_id, rest = _leading_id(tokens, "note")
+    if not rest:
+        raise ParseError("note needs some text")
+    return Note(task_id, " ".join(rest))
+
+
+def _show(tokens: Sequence[str], today: date) -> Command:
+    ids = _ids(tokens, "show")
+    if len(ids) > 1:
+        raise ParseError("show takes a single task id")
+    return Show(ids[0])
+
+
+def _listing(tokens: Sequence[str], today: date) -> Command:
+    status: Status | None = Status.PENDING
+    tags: set[str] = set()
+    without_tags: set[str] = set()
+    terms: list[str] = []
+    project: str | None = None
+    due_by: date | None = None
+    overdue = False
+
+    for token in tokens:
+        key, separator, value = token.partition(":")
+        if token == "done":
+            status = Status.DONE
+        elif token == "all":
+            status = None
+        elif token == "overdue":
+            overdue = True
+        elif _prefixed(token, "@"):
+            project = token[1:]
+        elif _prefixed(token, "+"):
+            tags.add(token[1:])
+        elif _prefixed(token, "-"):
+            without_tags.add(token[1:])
+        elif separator and key == "due":
+            due_by = _read_due(value, today)
+        else:
+            terms.append(token)
+
+    return Listing(
+        Query(
+            status=status,
+            tags=frozenset(tags),
+            without_tags=frozenset(without_tags),
+            project=project,
+            due_by=due_by,
+            overdue=overdue,
+            terms=tuple(terms),
+        )
+    )
+
+
+def _attributes(tokens: Sequence[str], today: date, *, removals: bool) -> Attributes:
+    words: list[str] = []
+    changes: dict[str, Any] = {}
+    add_tags: set[str] = set()
+    remove_tags: set[str] = set()
+
+    for token in tokens:
+        key, separator, value = token.partition(":")
+        if token == "@":
+            changes["project"] = None
+        elif _prefixed(token, "@"):
+            changes["project"] = token[1:]
+        elif _prefixed(token, "+"):
+            add_tags.add(token[1:])
+        elif removals and _prefixed(token, "-"):
+            remove_tags.add(token[1:])
+        elif separator and key in _ATTRIBUTES:
+            name, read = _ATTRIBUTES[key]
+            changes[name] = read(value, today)
+        else:
+            words.append(token)
+
+    return Attributes(
+        tuple(words), changes, frozenset(add_tags), frozenset(remove_tags)
+    )
+
+
+def _prefixed(token: str, marker: str) -> bool:
+    return len(token) > 1 and token.startswith(marker)
+
+
+def _is_id(token: str) -> bool:
+    return token.isdigit()
+
+
+def _ids(tokens: Sequence[str], verb: str) -> tuple[int, ...]:
+    if not tokens:
+        raise ParseError(f"{verb} needs a task id")
+    for token in tokens:
+        if not _is_id(token):
+            raise ParseError(f"not a task id: {token!r}")
+    return tuple(int(token) for token in tokens)
+
+
+def _leading_id(tokens: Sequence[str], verb: str) -> tuple[int, Sequence[str]]:
+    if not tokens:
+        raise ParseError(f"{verb} needs a task id")
+    head, *rest = tokens
+    if not _is_id(head):
+        raise ParseError(f"not a task id: {head!r}")
+    return int(head), rest
+
+
+def _read_due(value: str, today: date) -> date | None:
+    if not value:
+        return None
+    try:
+        return parse_date(value, today)
+    except DateError as error:
+        raise ParseError(str(error)) from error
+
+
+def _read_priority(value: str, today: date) -> Priority | None:
+    if not value:
+        return None
+    for priority in Priority:
+        if value in (priority.value, priority.value[0]):
+            return priority
+    choices = ", ".join(item.value[0] for item in Priority)
+    raise ParseError(f"not a priority: {value!r} (use {choices})")
+
+
+def _read_recurrence(value: str, today: date) -> Recurrence | None:
+    if not value:
+        return None
+    try:
+        return Recurrence(value)
+    except ValueError:
+        choices = ", ".join(item.value for item in Recurrence)
+        raise ParseError(f"not a repeat: {value!r} (use {choices})") from None
+
+
+_ATTRIBUTES: dict[str, tuple[str, Callable[[str, date], Any]]] = {
+    "due": ("due", _read_due),
+    "p": ("priority", _read_priority),
+    "every": ("every", _read_recurrence),
+}
+
+_VERBS: dict[str, Callable[[Sequence[str], date], Command]] = {
+    "add": _add,
+    "list": _listing,
+    "done": _done,
+    "rm": _remove,
+    "edit": _edit,
+    "note": _note,
+    "show": _show,
+}

tsk/query.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+from datetime import date
+
+from tsk.model import Status, Task
+
+
+@dataclass(frozen=True, slots=True)
+class Query:
+    status: Status | None = Status.PENDING
+    tags: frozenset[str] = frozenset()
+    without_tags: frozenset[str] = frozenset()
+    project: str | None = None
+    due_by: date | None = None
+    overdue: bool = False
+    terms: tuple[str, ...] = ()
+
+    def matches(self, task: Task, today: date) -> bool:
+        return all(
+            test(task, today)
+            for test in (
+                self._status_matches,
+                self._tags_match,
+                self._project_matches,
+                self._dates_match,
+                self._terms_match,
+            )
+        )
+
+    def _status_matches(self, task: Task, today: date) -> bool:
+        return self.status is None or task.status is self.status
+
+    def _tags_match(self, task: Task, today: date) -> bool:
+        return self.tags <= task.tags and not (self.without_tags & task.tags)
+
+    def _project_matches(self, task: Task, today: date) -> bool:
+        return self.project is None or task.project == self.project
+
+    def _dates_match(self, task: Task, today: date) -> bool:
+        if self.overdue and not task.is_overdue(today):
+            return False
+        if self.due_by is None:
+            return True
+        return task.due is not None and task.due <= self.due_by
+
+    def _terms_match(self, task: Task, today: date) -> bool:
+        haystack = " ".join((task.description, *task.notes)).casefold()
+        return all(term.casefold() in haystack for term in self.terms)

tsk/render.py

@@ -0,0 +1,128 @@
+import os
+from collections.abc import Iterator, Sequence
+from datetime import date
+from typing import TextIO
+
+from tsk.dates import describe
+from tsk.model import Priority, Status, Task
+
+_CODES = {
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "cyan": "36",
+    "magenta": "35",
+}
+_PRIORITY_STYLES = {
+    Priority.HIGH: "red",
+    Priority.MEDIUM: "yellow",
+    Priority.LOW: "dim",
+}
+_GAP = "  "
+_LABEL_WIDTH = 11
+
+
+class Ink:
+    def __init__(self, *, enabled: bool) -> None:
+        self._enabled = enabled
+
+    def paint(self, text: str, style: str) -> str:
+        if not self._enabled or not text.strip():
+            return text
+        return f"\x1b[{_CODES[style]}m{text}\x1b[0m"
+
+
+def ink_for(stream: TextIO) -> Ink:
+    return Ink(enabled=stream.isatty() and "NO_COLOR" not in os.environ)
+
+
+class _Layout:
+    def __init__(self, tasks: Sequence[Task], today: date) -> None:
+        spans = [describe(task.due, today) for task in tasks if task.due]
+        self.id_width = max(len(str(task.id)) for task in tasks)
+        self.due_width = max((len(span) for span in spans), default=0)
+        self.show_due = bool(spans)
+        self.show_priority = any(task.priority for task in tasks)
+
+
+class Renderer:
+    def __init__(self, ink: Ink, today: date) -> None:
+        self._ink = ink
+        self._today = today
+
+    def table(self, tasks: Sequence[Task]) -> str:
+        if not tasks:
+            return "nothing to do"
+        layout = _Layout(tasks, self._today)
+        return "\n".join(self._row(task, layout) for task in tasks)
+
+    def detail(self, task: Task) -> str:
+        lines = [f"{self._ink.paint(str(task.id), 'dim')}{_GAP}{task.description}", ""]
+        lines.extend(
+            f"{_GAP}{self._ink.paint(label.ljust(_LABEL_WIDTH), 'dim')}{value}"
+            for label, value in self._facts(task)
+        )
+        if task.notes:
+            lines.extend(["", f"{_GAP}{self._ink.paint('notes', 'dim')}"])
+            lines.extend(f"{_GAP}  {note}" for note in task.notes)
+        return "\n".join(lines)
+
+    def _row(self, task: Task, layout: _Layout) -> str:
+        cells = [self._ink.paint(str(task.id).rjust(layout.id_width), "dim")]
+        if layout.show_priority:
+            cells.append(self._priority_cell(task))
+        if layout.show_due:
+            cells.append(self._due_cell(task, layout.due_width))
+        cells.append(self._summary(task))
+        return _GAP.join(cells)
+
+    def _priority_cell(self, task: Task) -> str:
+        if task.priority is None:
+            return " "
+        letter = task.priority.value[0].upper()
+        return self._ink.paint(letter, _PRIORITY_STYLES[task.priority])
+
+    def _due_cell(self, task: Task, width: int) -> str:
+        if task.due is None:
+            return " " * width
+        span = describe(task.due, self._today).ljust(width)
+        return self._ink.paint(span, self._due_style(task))
+
+    def _due_style(self, task: Task) -> str:
+        if task.is_overdue(self._today):
+            return "red"
+        if task.due == self._today and task.status is Status.PENDING:
+            return "yellow"
+        return "dim"
+
+    def _summary(self, task: Task) -> str:
+        description = task.description
+        if task.status is Status.DONE:
+            description = self._ink.paint(description, "dim")
+        parts = [description]
+        if task.project:
+            parts.append(self._ink.paint(f"@{task.project}", "cyan"))
+        parts.extend(self._ink.paint(f"+{tag}", "magenta") for tag in sorted(task.tags))
+        if task.every:
+            parts.append(self._ink.paint(f"every:{task.every.value}", "dim"))
+        if task.notes:
+            parts.append(self._ink.paint("*", "dim"))
+        return " ".join(parts)
+
+    def _facts(self, task: Task) -> Iterator[tuple[str, str]]:
+        yield "status", task.status.value
+        if task.project:
+            yield "project", task.project
+        if task.tags:
+            yield "tags", ", ".join(sorted(task.tags))
+        if task.due:
+            yield "due", f"{describe(task.due, self._today)} ({task.due.isoformat()})"
+        if task.priority:
+            yield "priority", task.priority.value
+        if task.every:
+            yield "repeats", task.every.value
+        yield "created", task.created.date().isoformat()
+        if task.completed:
+            yield "completed", task.completed.date().isoformat()

tsk/store.py

@@ -0,0 +1,125 @@
+import json
+import os
+import tempfile
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from tsk.model import Priority, Recurrence, Status, Task, Tasks
+
+
+class StoreError(RuntimeError):
+    """Raised when the task file cannot be used."""
+
+
+class Store:
+    VERSION = 1
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def read(self) -> Tasks:
+        if not self.path.exists():
+            return Tasks()
+        document = self._document()
+        if document.get("version", 0) > self.VERSION:
+            raise StoreError(f"{self.path} was written by a newer version of tsk")
+        try:
+            return Tasks(
+                (_revive(entry) for entry in document.get("tasks", ())),
+                issued=document.get("issued", 0),
+            )
+        except (KeyError, TypeError, ValueError) as error:
+            raise StoreError(f"{self.path} is unreadable: {error}") from error
+
+    def write(self, tasks: Tasks) -> None:
+        document = {
+            "version": self.VERSION,
+            "issued": tasks.issued,
+            "tasks": [_record(task) for task in tasks],
+        }
+        _write_atomically(self.path, json.dumps(document, indent=2) + "\n")
+
+    def _document(self) -> dict[str, Any]:
+        try:
+            document = json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as error:
+            raise StoreError(f"{self.path} is unreadable: {error}") from error
+        if not isinstance(document, dict):
+            raise StoreError(f"{self.path} is unreadable: expected a JSON object")
+        return document
+
+
+def default_path() -> Path:
+    override = os.environ.get("TSK_DATA")
+    if override:
+        return Path(override)
+    data_home = os.environ.get("XDG_DATA_HOME")
+    root = Path(data_home) if data_home else Path.home() / ".local" / "share"
+    return root / "tsk" / "tasks.json"
+
+
+def _record(task: Task) -> dict[str, Any]:
+    always: dict[str, Any] = {
+        "id": task.id,
+        "description": task.description,
+        "status": task.status.value,
+        "created": task.created.isoformat(),
+    }
+    sometimes: dict[str, Any] = {
+        "project": task.project,
+        "tags": sorted(task.tags),
+        "due": task.due.isoformat() if task.due else None,
+        "priority": task.priority.value if task.priority else None,
+        "every": task.every.value if task.every else None,
+        "notes": list(task.notes),
+        "completed": task.completed.isoformat() if task.completed else None,
+    }
+    return always | {key: value for key, value in sometimes.items() if value}
+
+
+def _revive(entry: dict[str, Any]) -> Task:
+    return Task(
+        id=entry["id"],
+        description=entry["description"],
+        status=Status(entry["status"]),
+        project=entry.get("project"),
+        tags=frozenset(entry.get("tags", ())),
+        due=date.fromisoformat(entry["due"]) if "due" in entry else None,
+        priority=Priority(entry["priority"]) if "priority" in entry else None,
+        every=Recurrence(entry["every"]) if "every" in entry else None,
+        notes=tuple(entry.get("notes", ())),
+        created=datetime.fromisoformat(entry["created"]),
+        completed=(
+            datetime.fromisoformat(entry["completed"]) if "completed" in entry else None
+        ),
+    )
+
+
+def _write_atomically(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    inherited = path.stat().st_mode & 0o777 if path.exists() else None
+    handle, name = tempfile.mkstemp(dir=path.parent, prefix=path.name, suffix=".tmp")
+    temporary = Path(name)
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as opened:
+            opened.write(text)
+            opened.flush()
+            os.fsync(opened.fileno())
+        if inherited is not None:
+            temporary.chmod(inherited)
+        temporary.replace(path)
+        _fsync_directory(path.parent)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def _fsync_directory(directory: Path) -> None:
+    if os.name != "posix":
+        return
+    handle = os.open(directory, os.O_RDONLY)
+    try:
+        os.fsync(handle)
+    finally:
+        os.close(handle)

tsk_todo-0.1.0.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: tsk-todo
+Version: 0.1.0
+Summary: Minimal todo CLI for the terminal. Pure Python, zero dependencies.
+Keywords: cli,todo,task,task-manager,productivity,terminal,gtd
+Author: michaelrbarley
+Author-email: michaelrbarley <301309661+michaelrbarley@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/michaelrbarley/tsk-todo
+Project-URL: Source, https://github.com/michaelrbarley/tsk-todo
+Project-URL: Issues, https://github.com/michaelrbarley/tsk-todo/issues
+Description-Content-Type: text/markdown
+
+# tsk
+
+A small task manager for the terminal.
+
+```
+$ tsk add water the plants @home +garden due:tomorrow every:weekly
+added 1: water the plants
+
+$ tsk add fix the login bug @work +urgent due:yesterday p:h
+added 2: fix the login bug
+
+$ tsk
+2  H  yesterday  fix the login bug @work +urgent
+1     tomorrow   water the plants @home +garden every:weekly
+```
+
+No daemon, no config file, no dependencies. Your tasks live in one JSON file you can read.
+
+## Install
+
+Needs Python 3.11 or newer.
+
+```
+git clone https://github.com/michaelrbarley/tsk-todo
+cd tsk-todo
+uv tool install .
+```
+
+The command is `tsk`. The package is `tsk-todo`, because `tsk` on PyPI belongs to something else.
+
+Or run it from the clone without installing anything:
+
+```
+uv run tsk
+```
+
+## The idea
+
+You type what you mean and `tsk` works out which parts are metadata:
+
+```
+tsk add renew the passport @admin +boring due:eom p:h
+```
+
+`@admin` is the project, `+boring` is a tag, `due:eom` is the end of this month, `p:h` is high
+priority. Everything left over is the task itself.
+
+Only `due:`, `p:` and `every:` are read as attributes, so ordinary text stays ordinary:
+
+```
+$ tsk add email bob@example.com about the invoice
+$ tsk add fix the -v flag
+$ tsk add ticket: replace the boiler
+```
+
+None of those pick up a project, a tag or an attribute. If it is not a form `tsk` knows, it is
+part of the description.
+
+## Commands
+
+```
+tsk                        list pending tasks
+tsk add <text> [attrs]     add a task
+tsk done <id>...           complete tasks
+tsk rm <id>...             delete tasks
+tsk edit <id> <attrs>      change a task
+tsk note <id> <text>       attach a note
+tsk show <id>              show one task in full
+tsk list [filters]         list tasks
+```
+
+`tsk 3` on its own is shorthand for `tsk show 3`.
+
+`done` and `rm` take several ids at once: `tsk done 2 5 9`.
+
+## Attributes
+
+Use these when adding or editing.
+
+```
+@project      set the project
++tag          add a tag
+-tag          remove a tag, when editing
+due:<when>    set a due date
+p:h|m|l       set priority, high medium or low
+every:<how>   reschedule on completion
+```
+
+Priority also accepts the full word, so `p:high` and `p:h` are the same.
+
+Editing changes only what you name. Everything else is left alone.
+
+```
+$ tsk edit 3 due:friday +urgent
+updated 3: read the book
+```
+
+To clear something, give it no value:
+
+```
+$ tsk edit 3 due: p: every:
+```
+
+A bare `@` clears the project. A leading `-` removes a tag.
+
+## Filters
+
+```
+tsk +garden              tagged garden
+tsk -work                not tagged work
+tsk @home                in the home project
+tsk overdue              past due
+tsk due:friday           due on or before friday
+tsk done                 completed tasks
+tsk all                  everything
+tsk plants               search descriptions and notes
+```
+
+Filters combine, and `list` is optional:
+
+```
+$ tsk @home +garden overdue
+$ tsk list @work due:eow
+```
+
+Bare words search. `tsk list dentist` finds anything with dentist in the description or in a note.
+
+## Dates
+
+Anywhere a date is wanted:
+
+```
+today, tomorrow, yesterday
+monday .. sunday, or mon .. sun
+3d, 2w, 1m, 1y
+eow, eom, eoy
+2026-08-01
+```
+
+Weekday names mean the next one coming. On a Thursday, `due:thursday` is a week away, not today.
+
+Month and year offsets land on a real date. `1m` from the 31st of January is the 28th of February,
+not the 3rd of March.
+
+Due dates are plain calendar dates. `due:friday` means Friday wherever you happen to be, and it
+does not drift when you cross a timezone.
+
+## Repeats
+
+```
+every:daily
+every:weekdays
+every:weekly
+every:monthly
+every:yearly
+```
+
+A repeating task needs a due date. When you complete it, the next one is created for you:
+
+```
+$ tsk done 1
+done 1: water the plants
+  repeats as 5, due in 1 week
+```
+
+The next date is worked out from the old due date, then rolled forward until it is in the future.
+Finish a daily task five days late and the next one is due tomorrow, not last week. You never come
+back to a pile of overdue copies.
+
+Notes do not carry over. The completed task keeps them.
+
+## Notes
+
+```
+$ tsk note 3 the ferns look worse than the rest
+noted on 3: water the plants
+```
+
+Tasks with notes are marked with a `*` in the list. `tsk show 3` prints them.
+
+## Ordering
+
+Tasks sort by due date, then priority, then id. That is the whole rule. Nothing is scored or
+weighted behind your back, so the order is always one you can predict and explain.
+
+Undated tasks sort last. They are not urgent, they are just there.
+
+## Your data
+
+One JSON file, at `~/.local/share/tsk/tasks.json` unless you say otherwise:
+
+```json
+{
+  "version": 1,
+  "issued": 7,
+  "tasks": [
+    {
+      "id": 2,
+      "description": "fix the login bug",
+      "status": "pending",
+      "created": "2026-07-16T14:49:48+00:00",
+      "project": "work",
+      "tags": ["urgent"],
+      "due": "2026-07-15",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+Set `TSK_DATA` to put it somewhere else, or `XDG_DATA_HOME` to move the lot. Keep it in a git repo
+if you want history. Tags are written in a fixed order and absent fields are left out, so diffs
+stay small.
+
+Writes are atomic. The file is written beside itself and then moved into place, so an interrupted
+write cannot leave you with half a file. Existing permissions are preserved.
+
+Ids are never reused. Once id 3 has been handed out, no later task gets it, even if you delete task
+3 the same day. The id you read a minute ago is still the task you thought it was.
+
+## Colour
+
+On when writing to a terminal, off when piped. Set `NO_COLOR` to turn it off entirely.
+
+Overdue is red, due today is yellow, projects are cyan, tags are magenta.
+
+## What it does not do
+
+There is no urgency score, no dependency graph, no user defined attributes, no hooks, no custom
+report definitions and no sync. Each of those either failed the question "would I miss this" or
+costs far more than it returns for a tool this size.
+
+If you want a task on the calendar, `due:` is where it goes. If you want to find it later, tag it.
+That is most of task management.
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run mypy
+```
+
+The suite runs in well under a second. It is worth keeping it that way.
+
+## Licence
+
+MIT

tsk_todo-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tsk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tsk/cli.py,sha256=pUHfrYHousIZH9BUjPnyZJoGQ5Vn_iA_gk1Nj2nq3vo,6380
+tsk/dates.py,sha256=zJdUj6xsY3J6qVJChfdOax2DaUEH36ojSxwbQ6hCg3U,3288
+tsk/model.py,sha256=f2AmnSMkb9XlQCO4mTj08RJ2oQtaIFM7TIF82p1ERoo,3802
+tsk/parse.py,sha256=KtMyW9DVFOe0iXf40FS8irQCc1vPJMkP2k-sNXI7Lck,7155
+tsk/query.py,sha256=Yk-OS9ZTf6m7CQcUjWY3yq33LxvC1GBRDDj-DOv8-6Q,1605
+tsk/render.py,sha256=W3zThco2idEgGrcUZU6Gt-XNKpwQZXKLRtHGBp88te8,4422
+tsk/store.py,sha256=xv8PU5qLopqtOHgmgVxCa9XVPvSWTkOIO18ety51ePc,4258
+tsk_todo-0.1.0.dist-info/WHEEL,sha256=YR4QUxGCbsyoOnWBVTv-p1I4yc3seKGPev46mvmc8Cg,81
+tsk_todo-0.1.0.dist-info/entry_points.txt,sha256=rCSY00ZIUbG_BgUBegQaaOtWtxo1CZa7l0mid9rDnNo,38
+tsk_todo-0.1.0.dist-info/METADATA,sha256=p6dV4KLZ6FncImpA4sNXxJVQbRt5fE126NTZa7trxAc,7083
+tsk_todo-0.1.0.dist-info/RECORD,,

tsk_todo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.29
+Root-Is-Purelib: true
+Tag: py3-none-any

tsk_todo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tsk = tsk.cli:main
+