endpaper 0.0.1__py3-none-any.whl

endpaper/core/tasks.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from collections.abc import Iterable, Sequence
+from dataclasses import replace
+from datetime import date, datetime
+from pathlib import Path
+
+from endpaper.core.documents import _TOKEN_PATTERN, _validate_token
+from endpaper.core.errors import NotFoundError, UsageError, WorkspaceError
+from endpaper.core.models import ParsedTasks, ScanWarning, Task, TaskFilter, Workspace
+from endpaper.core.text import new_task_id, parse_tags
+
+_TASK_LINE = re.compile(
+    r"^(?P<indent>[ \t]*)(?P<marker>[-*+])[ \t]+\[(?P<state>[ xX])\][ \t]+(?P<rest>.*)$"
+)
+_IDVAL = re.compile(r"^[A-Za-z0-9_-]+$")
+_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_RECOGNIZED_KEYS = frozenset({"id", "type", "tags", "created"})
+_TERMINATORS = ("\r\n", "\n", "\r")
+
+TASKS_PATH = Path("tasks.md")
+
+
+def _split_terminator(line: str) -> tuple[str, str]:
+    for terminator in _TERMINATORS:
+        if line.endswith(terminator):
+            return line[: -len(terminator)], terminator
+    return line, ""
+
+
+def _split_comment(rest: str) -> tuple[str, str | None, bool]:
+    """Locate the last ``<!-- ... -->`` on the line, if any.
+
+    Returns (text_before, body, unterminated). `body` is None when there is no
+    `<!--` at all. `unterminated` is True when a `<!--` is opened but never closed.
+    """
+    idx = rest.rfind("<!--")
+    if idx == -1:
+        return rest, None, False
+    end = rest.find("-->", idx + 4)
+    if end == -1:
+        return rest, None, True
+    return rest[:idx], rest[idx + 4 : end], False
+
+
+def _classify_body(body: str) -> tuple[str, dict[str, str]]:
+    """Classify a closed comment's contents as bare / malformed / task."""
+    tokens = body.split()
+    fields: dict[str, str] = {}
+    has_recognized = False
+    has_unknown = False
+
+    for token in tokens:
+        key, sep, value = token.partition(":")
+        if sep and key in _RECOGNIZED_KEYS:
+            has_recognized = True
+            fields[key] = value
+        else:
+            has_unknown = True
+
+    if not has_recognized:
+        return "bare", {}
+    if has_unknown:
+        return "malformed", {}
+
+    if "id" in fields and not _IDVAL.match(fields["id"]):
+        return "malformed", {}
+    if "type" in fields and not _TOKEN_PATTERN.match(fields["type"]):
+        return "malformed", {}
+    if "tags" in fields:
+        tag_values = fields["tags"].split(",") if fields["tags"] else []
+        if not tag_values or any(not _TOKEN_PATTERN.match(tag) for tag in tag_values):
+            return "malformed", {}
+
+    return "task", fields
+
+
+def parse_tasks(text: str) -> ParsedTasks:
+    """Classify every line of a tasks.md document.
+
+    Never raises. Malformed lines become warnings, not exceptions.
+    ``"".join(result.lines) == text`` for any input.
+    """
+    raw_lines = text.splitlines(keepends=True)
+    tasks: list[Task] = []
+    warnings: list[ScanWarning] = []
+    needs_id: list[int] = []
+
+    for idx, raw_line in enumerate(raw_lines):
+        line_no = idx + 1
+        content, _terminator = _split_terminator(raw_line)
+
+        match = _TASK_LINE.match(content)
+        if match is None:
+            continue
+
+        rest = match.group("rest")
+        done = match.group("state") in ("x", "X")
+
+        before, body, unterminated = _split_comment(rest)
+
+        if body is None and not unterminated:
+            tasks.append(
+                Task(
+                    id=None,
+                    text=rest.rstrip(),
+                    done=done,
+                    type="",
+                    tags=(),
+                    created=None,
+                    line=line_no,
+                )
+            )
+            needs_id.append(idx)
+            continue
+
+        if unterminated:
+            warnings.append(
+                ScanWarning(
+                    path=TASKS_PATH,
+                    reason="task_unterminated_comment",
+                    message=f"tasks.md:{line_no}: unterminated comment on a task line",
+                )
+            )
+            continue
+
+        assert body is not None
+        classification, fields = _classify_body(body)
+
+        if classification == "bare":
+            tasks.append(
+                Task(
+                    id=None,
+                    text=rest.rstrip(),
+                    done=done,
+                    type="",
+                    tags=(),
+                    created=None,
+                    line=line_no,
+                )
+            )
+            needs_id.append(idx)
+            continue
+
+        if classification == "malformed":
+            warnings.append(
+                ScanWarning(
+                    path=TASKS_PATH,
+                    reason="task_malformed_comment",
+                    message=f"tasks.md:{line_no}: malformed metadata comment on a task line",
+                )
+            )
+            continue
+
+        task_id = fields.get("id")
+        task_type = fields.get("type", "")
+        tags_raw = fields.get("tags", "")
+        tags = tuple(tags_raw.split(",")) if tags_raw else ()
+
+        created_raw = fields.get("created")
+        created_value: date | None = None
+        if created_raw:
+            if _ISO_DATE.match(created_raw):
+                try:
+                    created_value = date.fromisoformat(created_raw)
+                except ValueError:
+                    created_value = None
+            if created_value is None:
+                warnings.append(
+                    ScanWarning(
+                        path=TASKS_PATH,
+                        reason="task_invalid_value",
+                        message=f"tasks.md:{line_no}: invalid created date {created_raw!r}",
+                    )
+                )
+
+        tasks.append(
+            Task(
+                id=task_id,
+                text=before.rstrip(),
+                done=done,
+                type=task_type,
+                tags=tags,
+                created=created_value,
+                line=line_no,
+            )
+        )
+
+    return ParsedTasks(
+        tasks=tuple(tasks),
+        warnings=tuple(warnings),
+        lines=tuple(raw_lines),
+        needs_id=tuple(needs_id),
+    )
+
+
+def _render_comment(
+    *, id: str, type: str = "", tags: Sequence[str] = (), created: date | None = None
+) -> str:
+    fields = [f"id:{id}"]
+    if type:
+        fields.append(f"type:{type}")
+    if tags:
+        fields.append(f"tags:{','.join(tags)}")
+    if created is not None:
+        fields.append(f"created:{created.isoformat()}")
+    return f"<!-- {' '.join(fields)} -->"
+
+
+def render_task_line(
+    text: str,
+    *,
+    done: bool = False,
+    id: str,
+    type: str = "",
+    tags: Sequence[str] = (),
+    created: date | None = None,
+) -> str:
+    """Render one task line, without a terminator.
+
+    Fields appear in the order id, type, tags, created; empty ones are omitted.
+    Raises UsageError if `text` is empty after stripping.
+    """
+    stripped = text.strip()
+    if not stripped:
+        raise UsageError("task text must not be empty")
+    checkbox = "x" if done else " "
+    comment = _render_comment(id=id, type=type, tags=tags, created=created)
+    return f"- [{checkbox}] {stripped} {comment}"
+
+
+def filter_tasks(tasks: Iterable[Task], f: TaskFilter) -> list[Task]:
+    """Conjunctive filter. Sorts oldest-first, undated last, stable within a date."""
+    results: list[Task] = []
+    for task in tasks:
+        if not f.include_done and task.done:
+            continue
+        if f.type is not None and task.type.lower() != f.type.lower():
+            continue
+        if f.tags:
+            task_tags = {tag.lower() for tag in task.tags}
+            if not all(tag.lower() in task_tags for tag in f.tags):
+                continue
+        results.append(task)
+    return sorted(results, key=lambda t: (t.created is None, t.created or date.min))
+
+
+def match_task(task: Task, query: str) -> bool:
+    """Case-insensitive substring over text, type, and tags. For the TUI's live filter."""
+    haystack = " ".join([task.text, task.type, *task.tags]).lower()
+    return query.lower() in haystack
+
+
+def _atomic_write(path: Path, lines: Sequence[str]) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+        tmp_path = Path(tmp_name)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="") as fh:
+                fh.write("".join(lines))
+            os.replace(tmp_path, path)
+        except BaseException:
+            tmp_path.unlink(missing_ok=True)
+            raise
+    except (PermissionError, OSError) as exc:
+        raise WorkspaceError(f"could not write {path}: {exc}") from exc
+
+
+def _read_text(path: Path) -> str:
+    try:
+        with open(path, encoding="utf-8", newline="") as fh:
+            return fh.read()
+    except OSError as exc:
+        raise WorkspaceError(f"could not read {path}: {exc}") from exc
+
+
+def load_tasks(workspace: Workspace) -> tuple[list[Task], list[ScanWarning]]:
+    """Read tasks.md, backfill missing identifiers in place, return records.
+
+    A missing tasks.md is an empty list, not an error. Backfill is best-effort: if
+    the file cannot be written, the affected tasks are returned with id=None plus
+    a warning, and the read still succeeds (FR-038).
+    """
+    path = workspace.tasks_file
+    if not path.exists():
+        return [], []
+
+    text = _read_text(path)
+    parsed = parse_tasks(text)
+    warnings = [replace(w, path=path) for w in parsed.warnings]
+    tasks = list(parsed.tasks)
+
+    if not parsed.needs_id:
+        return tasks, warnings
+
+    taken = {t.id for t in tasks if t.id is not None}
+    lines = list(parsed.lines)
+    id_map: dict[int, str] = {}
+    for idx in parsed.needs_id:
+        new_id = new_task_id(taken)
+        taken.add(new_id)
+        id_map[idx] = new_id
+        content, terminator = _split_terminator(lines[idx])
+        lines[idx] = f"{content} <!-- id:{new_id} -->{terminator}"
+
+    try:
+        _atomic_write(path, lines)
+    except WorkspaceError as exc:
+        warnings.append(
+            ScanWarning(
+                path=path,
+                reason="task_invalid_value",
+                message=f"could not backfill task ids: {exc}",
+            )
+        )
+        return tasks, warnings
+
+    return [
+        replace(task, id=id_map[task.line - 1]) if (task.line - 1) in id_map else task
+        for task in tasks
+    ], warnings
+
+
+def add_task(
+    workspace: Workspace,
+    description: str,
+    *,
+    type: str = "",
+    tags: Sequence[str] = (),
+    now: datetime | None = None,
+) -> Task:
+    """Append one task to tasks.md and return it.
+
+    Parses inline #tags out of `description` and merges them after `tags`, exactly
+    as create_document does. Creates tasks.md if absent. Every pre-existing byte is
+    preserved; if the file did not end with a newline, the terminator is added.
+    """
+    when = now or datetime.now()
+    title, inline_tags = parse_tags(description)
+    if not title:
+        raise UsageError("description must not be empty after removing #tag tokens")
+
+    normalized_type = _validate_token(type, "type") if type else ""
+    merged_tags: list[str] = []
+    for tag in (*tags, *inline_tags):
+        normalized = _validate_token(tag, "tag")
+        if normalized not in merged_tags:
+            merged_tags.append(normalized)
+
+    path = workspace.tasks_file
+    existing_text = _read_text(path) if path.exists() else ""
+    parsed = parse_tasks(existing_text)
+    taken = {t.id for t in parsed.tasks if t.id is not None}
+    new_id = new_task_id(taken)
+
+    rendered = render_task_line(
+        title,
+        done=False,
+        id=new_id,
+        type=normalized_type,
+        tags=tuple(merged_tags),
+        created=when.date(),
+    )
+
+    lines = list(parsed.lines)
+    if lines:
+        last_content, last_terminator = _split_terminator(lines[-1])
+        if not last_terminator:
+            lines[-1] = last_content + "\n"
+    lines.append(rendered + "\n")
+
+    _atomic_write(path, lines)
+
+    return Task(
+        id=new_id,
+        text=title,
+        done=False,
+        type=normalized_type,
+        tags=tuple(merged_tags),
+        created=when.date(),
+        line=len(lines),
+    )
+
+
+def _format_line_numbers(numbers: Sequence[int]) -> str:
+    if len(numbers) == 2:
+        return f"{numbers[0]} and {numbers[1]}"
+    return ", ".join(str(n) for n in numbers[:-1]) + f", and {numbers[-1]}"
+
+
+def set_task_state(workspace: Workspace, task_id: str, *, done: bool) -> Task:
+    """Set one task's checkbox and return the task as it now stands.
+
+    Re-reads and re-parses before writing; locates by id, never by a cached line
+    number. Changes exactly one character on that line. No-op (no write) if the
+    task already has the requested state.
+    """
+    path = workspace.tasks_file
+    if not path.exists():
+        raise NotFoundError(f"no task with id {task_id!r}")
+
+    text = _read_text(path)
+    parsed = parse_tasks(text)
+    matches = [t for t in parsed.tasks if t.id == task_id]
+
+    if not matches:
+        raise NotFoundError(f"no task with id {task_id!r}")
+    if len(matches) > 1:
+        line_numbers = _format_line_numbers([t.line for t in matches])
+        raise UsageError(
+            f"id {task_id!r} appears on lines {line_numbers}; "
+            "edit tasks.md to give one of them a different id"
+        )
+
+    task = matches[0]
+    if task.done == done:
+        return task
+
+    lines = list(parsed.lines)
+    idx = task.line - 1
+    content, terminator = _split_terminator(lines[idx])
+    match = _TASK_LINE.match(content)
+    assert match is not None
+    state_start, state_end = match.span("state")
+    new_char = "x" if done else " "
+    lines[idx] = content[:state_start] + new_char + content[state_end:] + terminator
+
+    _atomic_write(path, lines)
+
+    return replace(task, done=done)

endpaper/core/templates/AGENTS.md.tmpl

@@ -0,0 +1,62 @@
+# endpaper workspace
+
+Plain Markdown files with YAML frontmatter, no database. Every command below is
+non-interactive and produces stable, parseable output.
+
+## Layout
+
+```
+.endpaper/config.toml      workspace marker, do not edit
+meetings/YYYY/MM/          one markdown file per meeting
+notes/YYYY/MM/             one markdown file per typed or untyped note
+notes/daily/YYYY/MM/       one markdown file per day, named YYYY-MM-DD.md
+tasks.md                   one checkbox line per task, at the workspace root
+AGENTS.md                  this file
+```
+
+## Frontmatter
+
+Every file in `meetings/` and `notes/` starts with exactly these six keys:
+
+```yaml
+---
+id: m_20260728_a1b2c3d4
+type: "standup"
+title: "Q3 planning"
+tags: ["platform"]
+created: 2026-07-28T09:14:00
+updated: 2026-07-28T09:14:00
+---
+```
+
+`id` is prefixed `m_` for meetings, `n_` for notes. `type` is `""` when untyped; `tags` is `[]`.
+
+## Tasks
+
+One checkbox line per task in `tasks.md`, metadata in a trailing HTML comment (invisible in
+any markdown viewer). `[ ]` open, `[x]` done; a bare `- [ ] ...` gets an `id` on the next scan:
+
+```
+- [ ] send the vendor comparison <!-- id:t_a1b2 type:followup tags:procurement created:2026-07-28 -->
+```
+
+## Commands
+
+```bash
+endpaper meeting new "Q3 planning" --type standup --tag platform
+endpaper meeting list --json --type standup --tag platform --since 2026-07-01
+endpaper note today                                      # open/create today's note
+endpaper note new "vendor landscape" --type research --tag procurement
+endpaper note list --json --type daily --since 2026-07-01
+endpaper task add "send the vendor comparison" --type followup --tag procurement
+endpaper task list --json --all --type followup --tag procurement
+endpaper task done t_a1b2                                 # endpaper task undone t_a1b2
+```
+
+`--tag` is repeatable and the supported way to attach tags on the command line -- an unquoted
+`#tag` is eaten by the shell first; a `#tag` inside a *quoted* description is parsed out too.
+
+## Exit codes
+
+`0` success · `1` not found · `2` usage error · `3` workspace error. Diagnostics go to
+stderr; data goes to stdout; the two are never interleaved.

endpaper/core/templates/CLAUDE.md.tmpl

@@ -0,0 +1,8 @@
+# endpaper workspace
+
+This directory is an endpaper workspace. Before creating or changing anything here, read
+`AGENTS.md` in this same directory — it documents the commands, the layout, and the file
+format this tool expects.
+
+The one thing worth stating twice: create new files through the commands in `AGENTS.md`,
+not by hand. Once a file exists, edit its Markdown body directly like any other file.

endpaper/core/text.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+import secrets
+import unicodedata
+from collections.abc import Container
+from datetime import date
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+_TAG_TOKEN = re.compile(r"#([A-Za-z0-9][A-Za-z0-9_-]*)")
+_WHITESPACE = re.compile(r"\s+")
+
+
+def slugify(text: str, *, max_length: int = 40) -> str:
+    normalized = unicodedata.normalize("NFKD", text)
+    without_marks = "".join(ch for ch in normalized if not unicodedata.combining(ch))
+    casefolded = without_marks.casefold()
+    collapsed = _NON_ALNUM.sub("-", casefolded)
+    stripped = collapsed.strip("-")
+    truncated = stripped[:max_length].rstrip("-")
+    return truncated or "untitled"
+
+
+def parse_tags(description: str) -> tuple[str, tuple[str, ...]]:
+    tags: list[str] = []
+    for match in _TAG_TOKEN.finditer(description):
+        tag = match.group(1).lower()
+        if tag not in tags:
+            tags.append(tag)
+
+    title = _TAG_TOKEN.sub(" ", description)
+    title = _WHITESPACE.sub(" ", title).strip()
+    return title, tuple(tags)
+
+
+def new_document_id(when: date, prefix: str) -> str:
+    return f"{prefix}{when:%Y%m%d}_{secrets.token_hex(4)}"
+
+
+def new_meeting_id(when: date) -> str:
+    return new_document_id(when, "m_")
+
+
+def new_task_id(taken: Container[str]) -> str:
+    while True:
+        candidate = f"t_{secrets.token_hex(2)}"
+        if candidate not in taken:
+            return candidate

endpaper/core/workspace.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from datetime import datetime
+from pathlib import Path
+
+from endpaper.core.errors import WorkspaceError
+from endpaper.core.models import InitResult, Workspace
+
+SUPPORTED_SCHEMA = 1
+_TEMPLATES_DIR = Path(__file__).parent / "templates"
+_GUIDANCE_TEMPLATES = {
+    "AGENTS.md": _TEMPLATES_DIR / "AGENTS.md.tmpl",
+    "CLAUDE.md": _TEMPLATES_DIR / "CLAUDE.md.tmpl",
+}
+
+
+def find_workspace(start: Path) -> Workspace:
+    current = start.resolve()
+    while True:
+        marker = current / ".endpaper" / "config.toml"
+        if marker.is_file():
+            _check_schema(marker)
+            return Workspace(root=current)
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    raise WorkspaceError(
+        "no workspace found in this directory or any parent. Run 'endpaper init' to create one."
+    )
+
+
+def _check_schema(marker: Path) -> None:
+    with marker.open("rb") as f:
+        data = tomllib.load(f)
+    schema = data.get("workspace", {}).get("schema")
+    if schema != SUPPORTED_SCHEMA:
+        raise WorkspaceError(
+            f"unsupported workspace schema {schema!r} in {marker}; "
+            f"this build only supports schema {SUPPORTED_SCHEMA}"
+        )
+
+
+def _write_guidance_file(target: Path, name: str) -> bool:
+    """Write one guidance file if absent. Returns True when written, False when an
+    existing file was left untouched. Uses O_EXCL so the guarantee is enforced by the
+    OS rather than a check-then-write race."""
+    template = _GUIDANCE_TEMPLATES[name].read_text(encoding="utf-8")
+    try:
+        fd = os.open(target / name, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        return False
+    with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(template)
+    return True
+
+
+def init_workspace(target: Path) -> InitResult:
+    target = target.resolve()
+    endpaper_dir = target / ".endpaper"
+    if endpaper_dir.exists():
+        raise WorkspaceError(f"this directory is already an endpaper workspace: {target}")
+
+    (target / "meetings").mkdir(parents=True, exist_ok=True)
+    (target / "notes" / "daily").mkdir(parents=True, exist_ok=True)
+    (target / "tasks.md").touch(exist_ok=True)
+
+    written: list[str] = []
+    skipped: list[str] = []
+    for name in ("AGENTS.md", "CLAUDE.md"):
+        if _write_guidance_file(target, name):
+            written.append(name)
+        else:
+            skipped.append(name)
+
+    endpaper_dir.mkdir(parents=True, exist_ok=True)
+    now = datetime.now().replace(microsecond=0).isoformat()
+    (endpaper_dir / "config.toml").write_text(
+        f'[workspace]\nschema = {SUPPORTED_SCHEMA}\ncreated = "{now}"\n',
+        encoding="utf-8",
+    )
+
+    return InitResult(
+        workspace=Workspace(root=target), written=tuple(written), skipped=tuple(skipped)
+    )