mdtodo 0.1.0__tar.gz

mdtodo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mjws4oss
+
+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.

mdtodo-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: mdtodo
+Version: 0.1.0
+Summary: A todo list manager that keeps projects and tasks in a plain markdown file.
+Keywords: todo,markdown,cli
+Author: mjws4oss
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# mdtodo
+
+`mdtodo` is a command-line todo manager that keeps everything in one plain markdown file.
+Headings are projects and checkbox items are tasks. You can edit the file in any editor, or
+use the `mdtodo` commands. Either way, it stays readable markdown.
+
+```markdown
+- [ ] Call the bank due:2026-10-20
+
+## Website
+- [ ] Write landing copy @active due:2026-10-18
+- [ ] Pick a color palette @next
+  - [ ] Shortlist 3 palettes
+- [x] Buy domain
+```
+
+- `[ ]` means open, and `[x]` means completed.
+- `@active` marks a task you're working on now. `@next` adds a task to the pool of tasks
+  you plan to pick up next.
+- `due:YYYY-MM-DD` sets a deadline. Open tasks are flagged as overdue, or as due soon
+  (today through the next 3 days).
+- Tasks above the first heading go into the `Inbox` project. Prose, notes, and code blocks
+  are ignored.
+
+The full syntax is in
+[specs/001-markdown-todo-manager/contracts/file-format.md](specs/001-markdown-todo-manager/contracts/file-format.md).
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) installed:
+
+```bash
+uv tool install mdtodo   # puts `mdtodo` on your PATH (~/.local/bin)
+mdtodo --version
+```
+
+If you don't have a suitable Python, uv downloads one for you.
+
+```bash
+uv tool install mdtodo==X.Y.Z   # install a specific version
+uv tool upgrade mdtodo          # move to the latest release
+uv tool uninstall mdtodo        # remove the command
+```
+
+Uninstalling removes only the command. Your todo file (`~/tracker.md`, or whatever `--file`
+or `MDTODO_FILE` points at) is left untouched.
+
+**Switching from an editable install**: if you installed with `uv tool install --editable .`,
+run `uv tool uninstall mdtodo` first, or replace it in one step with
+`uv tool install --force mdtodo`.
+
+## Which file is used
+
+The first match wins:
+
+1. `--file PATH`, which can go before or after the command;
+2. the `MDTODO_FILE` environment variable;
+3. `~/tracker.md`.
+
+If you used an earlier version that read `~/TODO.md`, rename that file to `~/tracker.md`, or
+point `--file` or `MDTODO_FILE` at it.
+
+`mdtodo init` creates a starter file. Nothing else ever creates the file.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `mdtodo` / `mdtodo summary` | Active, Next, Overdue, and Due soon tasks, plus counts per project |
+| `mdtodo list [--all] [--project NAME]` | Tasks grouped by project, each with its reference |
+| `mdtodo next` | The next pool, ordered by deadline |
+| `mdtodo due` | Open tasks ordered by deadline |
+| `mdtodo start REF` / `mdtodo stop REF` | Add or remove `@active` |
+| `mdtodo next add REF` / `mdtodo next rm REF` | Add or remove `@next` |
+| `mdtodo done REF` | Check the box, and remove `@active` and `@next` |
+| `mdtodo init` | Create a starter file |
+
+`REF` is the 6-character reference shown in every listing. It stays the same when markers
+change. If you edit a task's text, its reference changes, and the old one is refused rather
+than applied to the wrong task. Each command changes only the task's own line. If the file
+changed while the command was running, nothing is written.
+
+Details, including output formats and exit codes, are in
+[contracts/cli.md](specs/001-markdown-todo-manager/contracts/cli.md).
+
+## Development
+
+```bash
+uv sync
+uv tool install --editable .       # installs this working tree as the `mdtodo` command
+scripts/check.sh                   # format, lint, mypy --strict, tests (coverage ≥ 80%)
+uv run pytest -m perf --no-cov     # timing checks (SC-002), kept out of the default run
+```
+
+The design documents are in [specs/001-markdown-todo-manager/](specs/001-markdown-todo-manager/),
+and the project principles are in [.specify/memory/constitution.md](.specify/memory/constitution.md).
+
+## Releasing
+
+Releases go to PyPI with `scripts/release.sh`. See [docs/releasing.md](docs/releasing.md).

mdtodo-0.1.0/README.md

@@ -0,0 +1,100 @@
+# mdtodo
+
+`mdtodo` is a command-line todo manager that keeps everything in one plain markdown file.
+Headings are projects and checkbox items are tasks. You can edit the file in any editor, or
+use the `mdtodo` commands. Either way, it stays readable markdown.
+
+```markdown
+- [ ] Call the bank due:2026-10-20
+
+## Website
+- [ ] Write landing copy @active due:2026-10-18
+- [ ] Pick a color palette @next
+  - [ ] Shortlist 3 palettes
+- [x] Buy domain
+```
+
+- `[ ]` means open, and `[x]` means completed.
+- `@active` marks a task you're working on now. `@next` adds a task to the pool of tasks
+  you plan to pick up next.
+- `due:YYYY-MM-DD` sets a deadline. Open tasks are flagged as overdue, or as due soon
+  (today through the next 3 days).
+- Tasks above the first heading go into the `Inbox` project. Prose, notes, and code blocks
+  are ignored.
+
+The full syntax is in
+[specs/001-markdown-todo-manager/contracts/file-format.md](specs/001-markdown-todo-manager/contracts/file-format.md).
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) installed:
+
+```bash
+uv tool install mdtodo   # puts `mdtodo` on your PATH (~/.local/bin)
+mdtodo --version
+```
+
+If you don't have a suitable Python, uv downloads one for you.
+
+```bash
+uv tool install mdtodo==X.Y.Z   # install a specific version
+uv tool upgrade mdtodo          # move to the latest release
+uv tool uninstall mdtodo        # remove the command
+```
+
+Uninstalling removes only the command. Your todo file (`~/tracker.md`, or whatever `--file`
+or `MDTODO_FILE` points at) is left untouched.
+
+**Switching from an editable install**: if you installed with `uv tool install --editable .`,
+run `uv tool uninstall mdtodo` first, or replace it in one step with
+`uv tool install --force mdtodo`.
+
+## Which file is used
+
+The first match wins:
+
+1. `--file PATH`, which can go before or after the command;
+2. the `MDTODO_FILE` environment variable;
+3. `~/tracker.md`.
+
+If you used an earlier version that read `~/TODO.md`, rename that file to `~/tracker.md`, or
+point `--file` or `MDTODO_FILE` at it.
+
+`mdtodo init` creates a starter file. Nothing else ever creates the file.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `mdtodo` / `mdtodo summary` | Active, Next, Overdue, and Due soon tasks, plus counts per project |
+| `mdtodo list [--all] [--project NAME]` | Tasks grouped by project, each with its reference |
+| `mdtodo next` | The next pool, ordered by deadline |
+| `mdtodo due` | Open tasks ordered by deadline |
+| `mdtodo start REF` / `mdtodo stop REF` | Add or remove `@active` |
+| `mdtodo next add REF` / `mdtodo next rm REF` | Add or remove `@next` |
+| `mdtodo done REF` | Check the box, and remove `@active` and `@next` |
+| `mdtodo init` | Create a starter file |
+
+`REF` is the 6-character reference shown in every listing. It stays the same when markers
+change. If you edit a task's text, its reference changes, and the old one is refused rather
+than applied to the wrong task. Each command changes only the task's own line. If the file
+changed while the command was running, nothing is written.
+
+Details, including output formats and exit codes, are in
+[contracts/cli.md](specs/001-markdown-todo-manager/contracts/cli.md).
+
+## Development
+
+```bash
+uv sync
+uv tool install --editable .       # installs this working tree as the `mdtodo` command
+scripts/check.sh                   # format, lint, mypy --strict, tests (coverage ≥ 80%)
+uv run pytest -m perf --no-cov     # timing checks (SC-002), kept out of the default run
+```
+
+The design documents are in [specs/001-markdown-todo-manager/](specs/001-markdown-todo-manager/),
+and the project principles are in [.specify/memory/constitution.md](.specify/memory/constitution.md).
+
+## Releasing
+
+Releases go to PyPI with `scripts/release.sh`. See [docs/releasing.md](docs/releasing.md).

mdtodo-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "mdtodo"
+version = "0.1.0"
+description = "A todo list manager that keeps projects and tasks in a plain markdown file."
+readme = "README.md"
+authors = [{ name = "mjws4oss" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["todo", "markdown", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+mdtodo = "mdtodo.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.16,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.1",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "PL", "PT"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests compare against literal values such as exit codes and counts.
+"tests/**" = ["PLR2004"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+python_version = "3.14"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -m 'not perf' --cov=mdtodo --cov-report=term-missing --cov-fail-under=80"
+markers = ["perf: timing-sensitive performance tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["mdtodo"]

mdtodo-0.1.0/src/mdtodo/__init__.py

@@ -0,0 +1,5 @@
+"""mdtodo: a todo list manager backed by a markdown file."""
+
+from importlib.metadata import version
+
+__version__ = version("mdtodo")

mdtodo-0.1.0/src/mdtodo/__main__.py

@@ -0,0 +1,3 @@
+from mdtodo.cli import main
+
+raise SystemExit(main())

mdtodo-0.1.0/src/mdtodo/cli.py

@@ -0,0 +1,202 @@
+"""`todo` command-line interface (contracts/cli.md)."""
+
+import argparse
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from mdtodo import __version__, edits, queries, refs, render, store
+from mdtodo.model import Task, TodoError, TodoFile
+from mdtodo.parser import parse
+
+
+def today() -> date:
+    return date.today()
+
+
+_FILE_HELP = "todo file to use (default: $MDTODO_FILE, then ~/tracker.md)"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # Subcommands also accept --file; SUPPRESS keeps them from overwriting a --file given
+    # before the command. The main parser gets its own action: `parents=` shares action
+    # objects, so a shared action's default would leak between parsers.
+    file_option = argparse.ArgumentParser(add_help=False)
+    file_option.add_argument("--file", metavar="PATH", default=argparse.SUPPRESS, help=_FILE_HELP)
+
+    parser = argparse.ArgumentParser(
+        prog="mdtodo",
+        description="Manage todos kept in a markdown file. With no command, shows the summary.",
+    )
+    parser.add_argument("--file", metavar="PATH", default=None, help=_FILE_HELP)
+    parser.add_argument("--version", action="version", version=f"mdtodo {__version__}")
+    commands = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    commands.add_parser("summary", parents=[file_option], help="active, next, and due tasks")
+
+    list_cmd = commands.add_parser("list", parents=[file_option], help="tasks grouped by project")
+    list_cmd.add_argument("--all", action="store_true", help="include completed tasks")
+    list_cmd.add_argument("--project", metavar="NAME", help="only this project")
+
+    commands.add_parser("due", parents=[file_option], help="open tasks ordered by deadline")
+
+    next_cmd = commands.add_parser(
+        "next", parents=[file_option], help="list next tasks, or add/rm the next marker"
+    )
+    next_actions = next_cmd.add_subparsers(dest="next_action", metavar="ACTION")
+    for action, help_text in (("add", "mark a task as next"), ("rm", "unmark a next task")):
+        next_actions.add_parser(action, parents=[file_option], help=help_text).add_argument(
+            "ref", metavar="REF"
+        )
+
+    for name, help_text in (
+        ("start", "mark a task as active"),
+        ("stop", "unmark an active task"),
+        ("done", "mark a task as completed"),
+    ):
+        commands.add_parser(name, parents=[file_option], help=help_text).add_argument(
+            "ref", metavar="REF"
+        )
+
+    commands.add_parser("init", parents=[file_option], help="create a starter todo file")
+    return parser
+
+
+def load(args: argparse.Namespace) -> tuple[Path, TodoFile, bytes]:
+    path = store.locate(args.file, os.environ)
+    text, snapshot = store.read(path)
+    todo = parse(text)
+    if todo.warnings:
+        print(render.render_warnings(todo.warnings), file=sys.stderr)
+    return path, todo, snapshot
+
+
+def _cmd_summary(args: argparse.Namespace) -> None:
+    _, todo, _ = load(args)
+    now = today()
+    print(
+        render.render_summary(
+            active=queries.active_tasks(todo),
+            next_tasks=queries.next_pool(todo),
+            overdue=queries.overdue(todo, now),
+            due_soon=queries.due_soon(todo, now),
+            counts=queries.project_counts(todo),
+            today=now,
+        )
+    )
+
+
+def _cmd_due(args: argparse.Namespace) -> None:
+    _, todo, _ = load(args)
+    print(render.render_due(queries.by_deadline(todo), today()))
+
+
+@dataclass(frozen=True, slots=True)
+class _WriteAction:
+    verb: str  # shown as "<verb>: <ref>  <description>"
+    needs_open: bool  # refuse on completed tasks
+    is_satisfied: Callable[[Task], bool]
+    edit: Callable[[str], str]
+    satisfied_reason: str
+
+
+_WRITE_ACTIONS = {
+    "start": _WriteAction(
+        "started",
+        True,
+        lambda t: t.active_marker,
+        lambda line: edits.add_marker(line, edits.ACTIVE),
+        "already active",
+    ),
+    "stop": _WriteAction(
+        "stopped",
+        False,
+        lambda t: not t.active_marker,
+        lambda line: edits.remove_marker(line, edits.ACTIVE),
+        "not active",
+    ),
+    "next add": _WriteAction(
+        "queued",
+        True,
+        lambda t: t.next_marker,
+        lambda line: edits.add_marker(line, edits.NEXT),
+        "already a next task",
+    ),
+    "next rm": _WriteAction(
+        "unqueued",
+        False,
+        lambda t: not t.next_marker,
+        lambda line: edits.remove_marker(line, edits.NEXT),
+        "not a next task",
+    ),
+    "done": _WriteAction("done", True, lambda t: False, edits.complete, ""),
+}
+
+
+def _write(args: argparse.Namespace, action: _WriteAction) -> None:
+    path, todo, snapshot = load(args)
+    task = refs.resolve(todo, args.ref)
+    if action.needs_open and not task.is_open:
+        raise TodoError(f"task {task.ref} is already completed")
+    if action.is_satisfied(task):
+        print(f"nothing to change: {task.ref} is {action.satisfied_reason}")
+        return
+    new_line = action.edit(todo.lines[task.line_no - 1])
+    store.write_if_unchanged(
+        path, snapshot, edits.apply_line_edit(todo.lines, task.line_no, new_line)
+    )
+    print(f"{action.verb}: {task.ref}  {task.description}")
+
+
+def _cmd_write(args: argparse.Namespace) -> None:
+    _write(args, _WRITE_ACTIONS[args.command])
+
+
+def _cmd_next(args: argparse.Namespace) -> None:
+    if args.next_action is not None:
+        _write(args, _WRITE_ACTIONS[f"next {args.next_action}"])
+        return
+    _, todo, _ = load(args)
+    print(render.render_next(queries.next_pool(todo), today()))
+
+
+def _cmd_list(args: argparse.Namespace) -> None:
+    _, todo, _ = load(args)
+    if args.project is not None and args.project not in {p.name for p in todo.projects}:
+        print(f"note: no project named '{args.project}'", file=sys.stderr)
+    print(render.render_list(todo, show_completed=args.all, project=args.project, today=today()))
+
+
+def _cmd_init(args: argparse.Namespace) -> None:
+    path = store.locate(args.file, os.environ)
+    store.create(path, render.example_todo(today()))
+    print(f"created {path}")
+
+
+_COMMANDS: dict[str, Callable[[argparse.Namespace], None]] = {
+    "summary": _cmd_summary,
+    "list": _cmd_list,
+    "next": _cmd_next,
+    "due": _cmd_due,
+    "init": _cmd_init,
+    "start": _cmd_write,
+    "stop": _cmd_write,
+    "done": _cmd_write,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else 2
+    try:
+        _COMMANDS[args.command or "summary"](args)
+    except TodoError as exc:
+        print(f"mdtodo: error: {exc}", file=sys.stderr)
+        return 1
+    return 0

mdtodo-0.1.0/src/mdtodo/edits.py

@@ -0,0 +1,72 @@
+"""Pure single-line edits (contracts/file-format.md "Editing rules")."""
+
+import re
+from collections.abc import Sequence
+
+from mdtodo.parser import TASK_PATTERN, indent_width
+
+ACTIVE = "@active"
+NEXT = "@next"
+
+_CHECKBOX_PREFIX = re.compile(r"[ \t]*[-*+][ \t]+\[[ xX]\][ \t]*")
+
+
+def _split_ending(line: str) -> tuple[str, str]:
+    content = line.rstrip("\r\n")
+    return content, line[len(content) :]
+
+
+def _marker_pattern(marker: str) -> re.Pattern[str]:
+    return re.compile(rf"(?<!\S){re.escape(marker)}(?!\S)", re.IGNORECASE)
+
+
+def add_marker(line: str, marker: str) -> str:
+    """Append ` marker` before the line ending, unless the marker is already present."""
+    content, ending = _split_ending(line)
+    if _marker_pattern(marker).search(content):
+        return line
+    return f"{content.rstrip(' \t')} {marker}{ending}"
+
+
+def remove_marker(line: str, marker: str) -> str:
+    """Remove every occurrence of the marker word plus one adjacent space."""
+    content, ending = _split_ending(line)
+    while match := _marker_pattern(marker).search(content):
+        start, end = match.span()
+        if end < len(content) and content[end] in " \t":
+            end += 1
+        elif (
+            start > 0
+            and content[start - 1] in " \t"
+            and not _CHECKBOX_PREFIX.fullmatch(content[: start - 1])
+        ):
+            # Keep the separator right after the checkbox so the line stays a task.
+            start -= 1
+        content = content[:start] + content[end:]
+    return content + ending
+
+
+def complete(line: str) -> str:
+    """Mark the task completed (`[x]`) and drop its @active and @next markers."""
+    content, ending = _split_ending(line)
+    match = TASK_PATTERN.match(content)
+    if match is None:
+        raise ValueError(f"not a task line: {line!r}")
+    box = match.start("box")
+    completed = content[:box] + "x" + content[box + 1 :] + ending
+    return remove_marker(remove_marker(completed, ACTIVE), NEXT)
+
+
+def normalize_indent(line: str) -> str:
+    """Write the line's leading tabs as spaces, keeping its indent width (research R12)."""
+    rest = line.lstrip(" \t")
+    return " " * indent_width(line[: len(line) - len(rest)]) + rest
+
+
+def apply_line_edit(lines: Sequence[str], line_no: int, new_line: str) -> str:
+    """Return the full text with only line `line_no` (1-based) replaced.
+
+    Its leading tabs are written as spaces (research R12).
+    """
+    index = line_no - 1
+    return "".join([*lines[:index], normalize_indent(new_line), *lines[index + 1 :]])

mdtodo-0.1.0/src/mdtodo/model.py

@@ -0,0 +1,73 @@
+"""Immutable domain model parsed from the todo file (see data-model.md)."""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import date
+from typing import Literal
+
+type Status = Literal["open", "completed"]
+
+# One nesting level, shared by everything that reads or writes indentation (research R12).
+INDENT = "  "
+
+
+class TodoError(Exception):
+    """Base class for errors reported to the user as `mdtodo: error: <message>`."""
+
+
+@dataclass(frozen=True, slots=True)
+class ParseWarning:
+    line_no: int
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    ref: str
+    line_no: int
+    indent: int
+    description: str
+    raw_text: str
+    status: Status
+    active_marker: bool
+    next_marker: bool
+    deadline: date | None
+    deadline_raw: str | None
+    deadline_invalid: bool
+    parent_ref: str | None
+    project: str
+
+    @property
+    def is_open(self) -> bool:
+        return self.status == "open"
+
+    @property
+    def is_active(self) -> bool:
+        # Completion wins over the active marker (spec edge case).
+        return self.active_marker and self.is_open
+
+    @property
+    def is_next(self) -> bool:
+        return self.next_marker and self.is_open
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    name: str
+    heading_lines: tuple[int, ...]
+    tasks: tuple[Task, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TodoFile:
+    lines: tuple[str, ...]
+    projects: tuple[Project, ...]
+    warnings: tuple[ParseWarning, ...]
+
+    def all_tasks(self) -> list[Task]:
+        """Every task in file order."""
+        return sorted(self._iter_tasks(), key=lambda task: task.line_no)
+
+    def _iter_tasks(self) -> Iterator[Task]:
+        for project in self.projects:
+            yield from project.tasks

mdtodo-0.1.0/src/mdtodo/parser.py

@@ -0,0 +1,192 @@
+"""Line-oriented parser for the todo file format (contracts/file-format.md)."""
+
+import re
+from dataclasses import dataclass, field
+from datetime import date
+
+from mdtodo.model import INDENT, ParseWarning, Project, Status, Task, TodoFile
+from mdtodo.refs import assign_refs
+
+INBOX = "Inbox"
+
+_FENCE = re.compile(r"^[ \t]*(?P<marker>```|~~~)")
+_HEADING = re.compile(r"^#{1,6}[ \t]+(?P<name>.*?)(?:[ \t]+#+)?[ \t]*$")
+TASK_PATTERN = re.compile(r"^(?P<indent>[ \t]*)[-*+][ \t]+\[(?P<box>[ xX])\][ \t]+(?P<text>.*)$")
+_BAD_CHECKBOX = re.compile(r"^[ \t]*[-*+][ \t]+(?P<box>\[[^ xX\]]\])[ \t]+")
+
+_ACTIVE = "@active"
+_NEXT = "@next"
+_DUE = "due:"
+
+
+@dataclass(frozen=True, slots=True)
+class Tokens:
+    description: str
+    active: bool
+    next: bool
+    deadline: date | None
+    deadline_raw: str | None
+    deadline_invalid: bool
+    warnings: tuple[str, ...]
+
+
+def parse_tokens(text: str) -> Tokens:
+    """Split task text into its description and markers (research R5)."""
+    words: list[str] = []
+    warnings: list[str] = []
+    active = next_ = False
+    deadline: date | None = None
+    deadline_raw: str | None = None
+    for token in text.split():
+        lowered = token.lower()
+        if lowered == _ACTIVE:
+            active = True
+        elif lowered == _NEXT:
+            next_ = True
+        elif lowered.startswith(_DUE):
+            if deadline_raw is not None:
+                warnings.append("multiple deadlines; using the first")
+                continue
+            deadline_raw = token[len(_DUE) :]
+            deadline = _parse_date(deadline_raw)
+            if deadline is None:
+                warnings.append(f"invalid date: {token}")
+        else:
+            words.append(token)
+    return Tokens(
+        description=" ".join(words),
+        active=active,
+        next=next_,
+        deadline=deadline,
+        deadline_raw=deadline_raw,
+        deadline_invalid=deadline_raw is not None and deadline is None,
+        warnings=tuple(warnings),
+    )
+
+
+def _parse_date(raw: str) -> date | None:
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", raw):
+        return None
+    try:
+        return date.fromisoformat(raw)
+    except ValueError:
+        return None
+
+
+def indent_width(indent: str) -> int:
+    """Width in columns, where a tab is one nesting level."""
+    return sum(len(INDENT) if ch == "\t" else 1 for ch in indent)
+
+
+@dataclass(slots=True)
+class _RawTask:
+    line_no: int
+    indent: int
+    raw_text: str
+    status: Status
+    tokens: Tokens
+    project: str
+    parent_index: int | None
+
+
+@dataclass(slots=True)
+class _ProjectBuilder:
+    heading_lines: list[int] = field(default_factory=list)
+    task_indices: list[int] = field(default_factory=list)
+
+
+def parse(text: str) -> TodoFile:
+    lines = tuple(text.splitlines(keepends=True))
+    projects: dict[str, _ProjectBuilder] = {}
+    raw_tasks: list[_RawTask] = []
+    warnings: list[ParseWarning] = []
+    current = INBOX
+    # (indent, index into raw_tasks) of possible parents in the current project.
+    parent_stack: list[tuple[int, int]] = []
+    fence: str | None = None
+
+    for line_no, line in enumerate(lines, start=1):
+        content = line.rstrip("\r\n")
+
+        fence_match = _FENCE.match(content)
+        if fence is not None:
+            if fence_match and fence_match["marker"] == fence:
+                fence = None
+            continue
+        if fence_match:
+            fence = fence_match["marker"]
+            continue
+
+        heading = _HEADING.match(content)
+        if heading and heading["name"]:
+            current = heading["name"]
+            projects.setdefault(current, _ProjectBuilder()).heading_lines.append(line_no)
+            parent_stack = []
+            continue
+
+        task_match = TASK_PATTERN.match(content)
+        if task_match is None:
+            bad = _BAD_CHECKBOX.match(content)
+            if bad:
+                warnings.append(ParseWarning(line_no, f"unrecognized checkbox: {bad['box']}"))
+            continue
+
+        indent = indent_width(task_match["indent"])
+        status: Status = "open" if task_match["box"] == " " else "completed"
+        tokens = parse_tokens(task_match["text"])
+        warnings.extend(ParseWarning(line_no, message) for message in tokens.warnings)
+        if status == "completed":
+            for marker, present in ((_NEXT, tokens.next), (_ACTIVE, tokens.active)):
+                if present:
+                    warnings.append(ParseWarning(line_no, f"marker on completed task: {marker}"))
+
+        while parent_stack and parent_stack[-1][0] >= indent:
+            parent_stack.pop()
+        parent_index = parent_stack[-1][1] if parent_stack else None
+
+        index = len(raw_tasks)
+        raw_tasks.append(
+            _RawTask(
+                line_no=line_no,
+                indent=indent,
+                raw_text=task_match["text"],
+                status=status,
+                tokens=tokens,
+                project=current,
+                parent_index=parent_index,
+            )
+        )
+        projects.setdefault(current, _ProjectBuilder()).task_indices.append(index)
+        parent_stack.append((indent, index))
+
+    task_refs = assign_refs([(raw.project, raw.tokens.description) for raw in raw_tasks])
+    tasks = [
+        Task(
+            ref=task_refs[i],
+            line_no=raw.line_no,
+            indent=raw.indent,
+            description=raw.tokens.description,
+            raw_text=raw.raw_text,
+            status=raw.status,
+            active_marker=raw.tokens.active,
+            next_marker=raw.tokens.next,
+            deadline=raw.tokens.deadline,
+            deadline_raw=raw.tokens.deadline_raw,
+            deadline_invalid=raw.tokens.deadline_invalid,
+            parent_ref=None if raw.parent_index is None else task_refs[raw.parent_index],
+            project=raw.project,
+        )
+        for i, raw in enumerate(raw_tasks)
+    ]
+    return TodoFile(
+        lines=lines,
+        projects=tuple(
+            Project(
+                name=name,
+                heading_lines=tuple(builder.heading_lines),
+                tasks=tuple(tasks[i] for i in builder.task_indices),
+            )
+            for name, builder in projects.items()
+        ),
+        warnings=tuple(sorted(warnings, key=lambda w: w.line_no)),
+    )

mdtodo-0.1.0/src/mdtodo/queries.py

@@ -0,0 +1,62 @@
+"""Read-only views over a parsed todo file (data-model.md "Queries")."""
+
+from datetime import date
+from typing import Literal
+
+from mdtodo.model import Task, TodoFile
+
+
+def project_counts(todo: TodoFile) -> list[tuple[str, int, int]]:
+    """(name, open, completed) for each project, in file order."""
+    return [
+        (
+            project.name,
+            sum(task.is_open for task in project.tasks),
+            sum(not task.is_open for task in project.tasks),
+        )
+        for project in todo.projects
+    ]
+
+
+def _deadline_order(task: Task) -> tuple[bool, date, int]:
+    """Earliest deadline first, no (or invalid) deadline last, then file order."""
+    return (task.deadline is None, task.deadline or date.max, task.line_no)
+
+
+def active_tasks(todo: TodoFile) -> list[Task]:
+    return [task for task in todo.all_tasks() if task.is_active]
+
+
+def next_pool(todo: TodoFile) -> list[Task]:
+    """Open tasks marked @next in any project (FR-009)."""
+    return sorted((task for task in todo.all_tasks() if task.is_next), key=_deadline_order)
+
+
+DUE_SOON_DAYS = 3
+
+type DueState = Literal["overdue", "due_soon", "none"]
+
+
+def due_state(task: Task, today: date) -> DueState:
+    """Overdue or due-soon flags apply only to open tasks with a valid deadline (FR-008)."""
+    if not task.is_open or task.deadline is None:
+        return "none"
+    days_left = (task.deadline - today).days
+    if days_left < 0:
+        return "overdue"
+    if days_left <= DUE_SOON_DAYS:
+        return "due_soon"
+    return "none"
+
+
+def overdue(todo: TodoFile, today: date) -> list[Task]:
+    return [task for task in by_deadline(todo) if due_state(task, today) == "overdue"]
+
+
+def due_soon(todo: TodoFile, today: date) -> list[Task]:
+    return [task for task in by_deadline(todo) if due_state(task, today) == "due_soon"]
+
+
+def by_deadline(todo: TodoFile) -> list[Task]:
+    """All open tasks across projects, earliest deadline first, undated last (FR-011)."""
+    return sorted((task for task in todo.all_tasks() if task.is_open), key=_deadline_order)

mdtodo-0.1.0/src/mdtodo/refs.py

@@ -0,0 +1,38 @@
+"""Stable, fixed-length task references (research R6)."""
+
+import hashlib
+from collections.abc import Sequence
+
+from mdtodo.model import Task, TodoError, TodoFile
+
+REF_LENGTH = 6
+
+
+class RefNotFound(TodoError):
+    def __init__(self, ref: str) -> None:
+        super().__init__(
+            f"task not found: {ref} (it may have been edited; run 'mdtodo list' for current refs)"
+        )
+        self.ref = ref
+
+
+def assign_refs(items: Sequence[tuple[str, str]]) -> list[str]:
+    """Return one ref per (project, description) pair, in the given file order."""
+    seen: dict[str, int] = {}
+    result: list[str] = []
+    for project, description in items:
+        digest = hashlib.sha1(f"{project}\n{description}".encode()).hexdigest()
+        base = digest[:REF_LENGTH]
+        count = seen.get(base, 0) + 1
+        seen[base] = count
+        result.append(base if count == 1 else f"{base}-{count}")
+    return result
+
+
+def resolve(todo: TodoFile, ref: str) -> Task:
+    """Find the task whose ref matches exactly, ignoring case. Prefixes never match."""
+    wanted = ref.strip().lower()
+    for task in todo.all_tasks():
+        if task.ref == wanted:
+            return task
+    raise RefNotFound(ref)

mdtodo-0.1.0/src/mdtodo/render.py

@@ -0,0 +1,114 @@
+"""Plain-text output for the CLI (contracts/cli.md)."""
+
+from collections.abc import Iterable, Sequence
+from datetime import date, timedelta
+
+from mdtodo.model import INDENT, ParseWarning, Task, TodoFile
+from mdtodo.queries import due_state
+
+EMPTY_LIST = "(no tasks)"
+EMPTY_SECTION = f"{INDENT}(none)"
+EMPTY_NEXT = "No next tasks. Mark one with: mdtodo next add <ref>"
+
+_DUE_FLAGS = {"overdue": ", overdue", "due_soon": ", due soon", "none": ""}
+
+
+def example_todo(today: date) -> str:
+    """Starter file for `mdtodo init`, with deadlines relative to today."""
+
+    def due(days: int) -> str:
+        return f"due:{(today + timedelta(days=days)).isoformat()}"
+
+    return f"""- [ ] Call the bank {due(3)}
+
+## Website
+- [ ] Write landing copy @active {due(1)}
+- [ ] Pick a color palette @next
+{INDENT}- [ ] Shortlist 3 palettes
+- [x] Buy domain
+
+Notes and plain text like this line are ignored.
+
+## Garden
+- [ ] Order seeds @next {due(14)}
+- [ ] Fix the fence
+"""
+
+
+def render_warnings(warnings: Iterable[ParseWarning]) -> str:
+    return "\n".join(f"warning: line {w.line_no}: {w.message}" for w in warnings)
+
+
+def _deadline_suffix(task: Task, today: date) -> str:
+    if task.deadline_invalid:
+        return f"  (due {task.deadline_raw}, invalid date)"
+    if task.deadline is None:
+        return ""
+    return f"  (due {task.deadline.isoformat()}{_DUE_FLAGS[due_state(task, today)]})"
+
+
+def render_task_line(task: Task, today: date, with_project: bool = True) -> str:
+    project = f"[{task.project}] " if with_project else ""
+    return f"{task.ref}  {project}{task.description}{_deadline_suffix(task, today)}"
+
+
+def _depths(tasks: Iterable[Task]) -> dict[str, int]:
+    depths: dict[str, int] = {}
+    for task in tasks:  # file order guarantees parents come first
+        depths[task.ref] = 0 if task.parent_ref is None else depths[task.parent_ref] + 1
+    return depths
+
+
+def render_list(todo: TodoFile, show_completed: bool, project: str | None, today: date) -> str:
+    depths = _depths(todo.all_tasks())
+    groups: list[str] = []
+    for proj in todo.projects:
+        if project is not None and proj.name != project:
+            continue
+        lines = [
+            f"{INDENT * depths[task.ref]}{task.ref}  {'' if task.is_open else '[x] '}"
+            f"{task.description}{_deadline_suffix(task, today)}"
+            for task in proj.tasks
+            if show_completed or task.is_open
+        ]
+        if lines:
+            groups.append("\n".join([f"## {proj.name}", *lines]))
+    return "\n\n".join(groups) if groups else EMPTY_LIST
+
+
+def render_projects_section(counts: Iterable[tuple[str, int, int]]) -> str:
+    lines = [f"{INDENT}{name}  {open_} open, {done} done" for name, open_, done in counts]
+    return "\n".join(["Projects", *(lines or [EMPTY_SECTION])])
+
+
+def _section(title: str, tasks: Sequence[Task], today: date) -> str:
+    lines = [f"{INDENT}{render_task_line(task, today)}" for task in tasks]
+    return "\n".join([title, *(lines or [EMPTY_SECTION])])
+
+
+def render_summary(  # noqa: PLR0913 - one argument per summary section (contracts/cli.md)
+    *,
+    active: Sequence[Task],
+    next_tasks: Sequence[Task],
+    overdue: Sequence[Task],
+    due_soon: Sequence[Task],
+    counts: Iterable[tuple[str, int, int]],
+    today: date,
+) -> str:
+    return "\n\n".join(
+        [
+            _section("Active", active, today),
+            _section("Next", next_tasks, today),
+            _section("Overdue", overdue, today),
+            _section("Due soon", due_soon, today),
+            render_projects_section(counts),
+        ]
+    )
+
+
+def render_next(tasks: Sequence[Task], today: date) -> str:
+    return "\n".join(render_task_line(task, today) for task in tasks) if tasks else EMPTY_NEXT
+
+
+def render_due(tasks: Sequence[Task], today: date) -> str:
+    return "\n".join(render_task_line(task, today) for task in tasks) if tasks else EMPTY_LIST

mdtodo-0.1.0/src/mdtodo/store.py

@@ -0,0 +1,96 @@
+"""Finding, reading, and safely writing the todo file (research R7, R8)."""
+
+import contextlib
+import os
+import stat
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+
+from mdtodo.model import TodoError
+
+ENV_VAR = "MDTODO_FILE"
+DEFAULT_NAME = "tracker.md"
+
+__all__ = [
+    "FileChangedError",
+    "TodoError",
+    "TodoFileExists",
+    "TodoFileMissing",
+    "create",
+    "locate",
+    "read",
+    "write_if_unchanged",
+]
+
+
+class TodoFileMissing(TodoError):
+    def __init__(self, path: Path) -> None:
+        super().__init__(f"no todo file at {path}. Create one with 'mdtodo init' or set {ENV_VAR}.")
+
+
+class TodoFileExists(TodoError):
+    def __init__(self, path: Path) -> None:
+        super().__init__(f"{path} already exists; not overwriting it")
+
+
+class FileChangedError(TodoError):
+    def __init__(self) -> None:
+        super().__init__("file changed since it was read; nothing was written, please re-run")
+
+
+def locate(cli_path: str | None, env: Mapping[str, str]) -> Path:
+    """`--file`, then `$MDTODO_FILE`, then `~/tracker.md`."""
+    chosen = cli_path or env.get(ENV_VAR)
+    if chosen:
+        return Path(chosen).expanduser()
+    return Path.home() / DEFAULT_NAME
+
+
+def read(path: Path) -> tuple[str, bytes]:
+    """Return the file's text (line endings untouched) and the raw bytes as a snapshot."""
+    try:
+        snapshot = path.read_bytes()
+    except FileNotFoundError:
+        raise TodoFileMissing(path) from None
+    except OSError as exc:
+        raise TodoError(f"cannot read {path}: {exc.strerror}") from exc
+    try:
+        return snapshot.decode("utf-8"), snapshot
+    except UnicodeDecodeError:
+        raise TodoError(f"cannot read {path}: not valid UTF-8") from None
+
+
+def write_if_unchanged(path: Path, snapshot: bytes, new_text: str) -> None:
+    """Atomically replace the file, unless it changed since `snapshot` was read."""
+    if path.read_bytes() != snapshot:
+        raise FileChangedError
+    mode = stat.S_IMODE(path.stat().st_mode)
+    with tempfile.NamedTemporaryFile(
+        dir=path.parent, prefix=f".{path.name}.", suffix=".tmp", delete=False
+    ) as tmp:
+        tmp_path = Path(tmp.name)
+        try:
+            tmp.write(new_text.encode("utf-8"))
+            tmp.flush()
+            os.fsync(tmp.fileno())
+        except BaseException:
+            tmp.close()
+            tmp_path.unlink()
+            raise
+    try:
+        tmp_path.chmod(mode)
+        os.replace(tmp_path, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            tmp_path.unlink()
+        raise
+
+
+def create(path: Path, text: str) -> None:
+    """Create a new todo file; refuse if one already exists."""
+    try:
+        with path.open("xb") as handle:
+            handle.write(text.encode("utf-8"))
+    except FileExistsError:
+        raise TodoFileExists(path) from None