endpaper 0.0.1__py3-none-any.whl

endpaper/core/editing.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from endpaper.core.models import EditableFile, SaveResult
+
+_UPDATED_LINE = re.compile(r"^updated:.*$", re.MULTILINE)
+
+
+def stamp_updated(text: str, timestamp: str) -> tuple[str, bool]:
+    """Replace the value on the frontmatter block's first `updated:` line, changing no
+    other byte. Returns (new_text, True) when stamped, (text, False) when the block or
+    the line could not be located. Never raises.
+    """
+    if not text.startswith("---\n"):
+        return text, False
+
+    terminator = text.find("\n---", 3)
+    if terminator == -1:
+        return text, False
+
+    block = text[4 : terminator + 1]
+    match = _UPDATED_LINE.search(block)
+    if match is None:
+        return text, False
+
+    start = 4 + match.start()
+    end = 4 + match.end()
+    new_text = text[:start] + f"updated: {timestamp}" + text[end:]
+    return new_text, True
+
+
+def load_for_edit(path: Path) -> EditableFile:
+    """Read a file for editing: whole text including frontmatter, normalised to "\\n",
+    with the line-ending convention and trailing-newline state captured for restoration.
+
+    Raises:
+        OSError: the file cannot be read.
+    """
+    with open(path, encoding="utf-8", errors="replace", newline="") as f:
+        raw = f.read()
+
+    first_break = raw.find("\n")
+    if first_break > 0 and raw[first_break - 1] == "\r":
+        newline = "\r\n"
+    else:
+        newline = "\n"
+
+    trailing_newline = raw.endswith("\n")
+    text = raw.replace("\r\n", "\n")
+    return EditableFile(path=path, text=text, newline=newline, trailing_newline=trailing_newline)
+
+
+def _apply_line_ending_policy(text: str, newline: str, trailing_newline: bool) -> str:
+    if newline != "\n":
+        text = text.replace("\n", newline)
+    has_trailing = text.endswith("\n")
+    if trailing_newline and not has_trailing:
+        text = text + newline
+    elif not trailing_newline and has_trailing:
+        text = text[: -len(newline)]
+    return text
+
+
+def save_buffer(
+    path: Path,
+    text: str,
+    file: EditableFile,
+    *,
+    now: datetime | None = None,
+) -> SaveResult:
+    """Stamp `updated`, restore `file`'s line endings and trailing newline, and write
+    atomically to `path` via a same-directory temp file and os.replace.
+
+    Never raises on a write failure -- returns SaveResult(ok=False) with a
+    user-facing message, leaving the target byte-identical.
+    """
+    assert path == file.path
+
+    when = now or datetime.now()
+    timestamp = when.replace(microsecond=0).isoformat()
+    stamped_text, stamped = stamp_updated(text, timestamp)
+    out_text = _apply_line_ending_policy(stamped_text, file.newline, file.trailing_newline)
+
+    tmp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w", encoding="utf-8", newline="", dir=path.parent, delete=False, suffix=".tmp"
+        ) as tmp_file:
+            tmp_file.write(out_text)
+            tmp_path = Path(tmp_file.name)
+        os.replace(tmp_path, path)
+    except OSError as exc:
+        if tmp_path is not None and tmp_path.exists():
+            tmp_path.unlink()
+        return SaveResult(ok=False, saved_text="", stamped=False, message=str(exc))
+    return SaveResult(ok=True, saved_text=stamped_text, stamped=stamped, message="")

endpaper/core/errors.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+
+class EndpaperError(Exception):
+    """Base. Carries the exit code the CLI should use."""
+
+    exit_code: ClassVar[int]
+
+
+class NotFoundError(EndpaperError):
+    exit_code = 1
+
+
+class UsageError(EndpaperError):
+    exit_code = 2
+
+
+class WorkspaceError(EndpaperError):
+    exit_code = 3

endpaper/core/frontmatter.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+
+import yaml
+
+from endpaper.core.models import Document, ScanWarningReason
+
+REQUIRED_KEYS = frozenset({"id", "type", "title", "tags", "created", "updated"})
+
+_KEY_ORDER = ("id", "type", "title", "tags", "created", "updated")
+
+
+class FrontmatterError(Exception):
+    """Internal. Raised on a structural frontmatter problem; never escapes scan_meetings."""
+
+    def __init__(self, reason: ScanWarningReason, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.message = message
+
+
+def _construct_scalar_as_str(loader: yaml.SafeLoader, node: yaml.Node) -> str:
+    return str(loader.construct_scalar(node))  # type: ignore[arg-type]
+
+
+class _TolerantLoader(yaml.SafeLoader):
+    """Leaves YAML 1.1's bool/timestamp/float/int/null coercions as their original scalar text."""
+
+
+for _tag in (
+    "tag:yaml.org,2002:bool",
+    "tag:yaml.org,2002:timestamp",
+    "tag:yaml.org,2002:float",
+    "tag:yaml.org,2002:int",
+    "tag:yaml.org,2002:null",
+):
+    _TolerantLoader.add_constructor(_tag, _construct_scalar_as_str)
+
+
+def read_frontmatter(text: str) -> dict[str, str | list[str]]:
+    try:
+        data = yaml.load(text, Loader=_TolerantLoader)
+    except yaml.YAMLError as exc:
+        raise FrontmatterError("malformed_yaml", f"invalid YAML: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise FrontmatterError("not_a_mapping", "frontmatter is not a mapping")
+
+    keys = set(data)
+    extra = keys - REQUIRED_KEYS
+    missing = REQUIRED_KEYS - keys
+    if extra:
+        raise FrontmatterError("unexpected_fields", f"unexpected fields: {sorted(extra)}")
+    if missing:
+        raise FrontmatterError("missing_fields", f"missing fields: {sorted(missing)}")
+
+    result: dict[str, str | list[str]] = {}
+    for key, value in data.items():
+        if key == "tags":
+            if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                raise FrontmatterError("invalid_value", "tags must be a list of strings")
+            result[key] = list(value)
+        else:
+            if not isinstance(value, str):
+                raise FrontmatterError("invalid_value", f"{key} must be a scalar string")
+            result[key] = value
+    return result
+
+
+def _quoted(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def render_frontmatter(document: Document) -> str:
+    type_field = _quoted(document.type) if document.type else '""'
+    tags_field = "[" + ", ".join(_quoted(tag) for tag in document.tags) + "]"
+    lines = [
+        "---",
+        f"id: {document.id}",
+        f"type: {type_field}",
+        f"title: {_quoted(document.title)}",
+        f"tags: {tags_field}",
+        f"created: {document.created}",
+        f"updated: {document.updated}",
+        "---",
+        "",
+    ]
+    return "\n".join(lines) + "\n"

endpaper/core/meetings.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+
+from endpaper.core.documents import (
+    create_document,
+    filter_documents,
+    match_document,
+    scan_documents,
+)
+from endpaper.core.models import Collection, Document, DocumentFilter, ScanWarning, Workspace
+
+MEETINGS = Collection("m_", "meetings", ("meetings",), frozenset())
+
+
+def create_meeting(
+    workspace: Workspace,
+    description: str,
+    *,
+    type: str = "",
+    tags: Sequence[str] = (),
+    now: datetime | None = None,
+) -> Document:
+    return create_document(workspace, MEETINGS, description, type=type, tags=tags, now=now)
+
+
+def scan_meetings(workspace: Workspace) -> tuple[list[Document], list[ScanWarning]]:
+    return scan_documents(workspace, MEETINGS)
+
+
+def filter_meetings(meetings: Iterable[Document], f: DocumentFilter) -> list[Document]:
+    return filter_documents(meetings, f)
+
+
+def match_meeting(meeting: Document, query: str) -> bool:
+    return match_document(meeting, query)

endpaper/core/models.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class Workspace:
+    root: Path
+
+    @property
+    def meetings_dir(self) -> Path:
+        return self.root / "meetings"
+
+    @property
+    def notes_dir(self) -> Path:
+        return self.root / "notes"
+
+    @property
+    def daily_dir(self) -> Path:
+        return self.root / "notes" / "daily"
+
+    @property
+    def tasks_file(self) -> Path:
+        return self.root / "tasks.md"
+
+
+@dataclass(frozen=True, slots=True)
+class Document:
+    id: str
+    path: Path
+    title: str
+    type: str
+    tags: tuple[str, ...]
+    created: str
+    updated: str
+
+
+Meeting = Document
+Note = Document
+
+
+@dataclass(frozen=True, slots=True)
+class Collection:
+    id_prefix: str
+    create_dir: str
+    scan_dirs: tuple[str, ...]
+    reserved_types: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class DailyNote:
+    path: Path
+    document: Document | None
+    created: bool
+
+
+ScanWarningReason = Literal[
+    "no_frontmatter",
+    "unterminated_frontmatter",
+    "malformed_yaml",
+    "not_a_mapping",
+    "missing_fields",
+    "unexpected_fields",
+    "invalid_value",
+    "task_unterminated_comment",
+    "task_malformed_comment",
+    "task_invalid_value",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ScanWarning:
+    path: Path
+    reason: ScanWarningReason
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentFilter:
+    type: str | None = None
+    tags: tuple[str, ...] = ()
+    since: date | None = None
+
+
+MeetingFilter = DocumentFilter
+
+
+@dataclass(frozen=True, slots=True)
+class EditableFile:
+    path: Path
+    text: str
+    newline: str
+    trailing_newline: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SaveResult:
+    ok: bool
+    saved_text: str
+    stamped: bool
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class InitResult:
+    workspace: Workspace
+    written: tuple[str, ...]
+    skipped: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Task:
+    id: str | None
+    text: str
+    done: bool
+    type: str
+    tags: tuple[str, ...]
+    created: date | None
+    line: int
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedTasks:
+    tasks: tuple[Task, ...]
+    warnings: tuple[ScanWarning, ...]
+    lines: tuple[str, ...]
+    needs_id: tuple[int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TaskFilter:
+    type: str | None = None
+    tags: tuple[str, ...] = ()
+    include_done: bool = False

endpaper/core/notes.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from datetime import datetime
+
+from endpaper.core.documents import _read_document, create_document, scan_documents
+from endpaper.core.frontmatter import render_frontmatter
+from endpaper.core.models import Collection, DailyNote, Document, ScanWarning, Workspace
+from endpaper.core.text import new_document_id
+
+NOTES = Collection("n_", "notes", ("notes",), frozenset({"daily"}))
+
+
+def create_note(
+    workspace: Workspace,
+    description: str,
+    *,
+    type: str = "",
+    tags: Sequence[str] = (),
+    now: datetime | None = None,
+) -> Document:
+    return create_document(workspace, NOTES, description, type=type, tags=tags, now=now)
+
+
+def scan_notes(workspace: Workspace) -> tuple[list[Document], list[ScanWarning]]:
+    return scan_documents(workspace, NOTES)
+
+
+def open_daily_note(workspace: Workspace, *, now: datetime | None = None) -> DailyNote:
+    when = now or datetime.now()
+    path = workspace.daily_dir / f"{when:%Y/%m}" / f"{when:%Y-%m-%d}.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    timestamp = when.replace(microsecond=0).isoformat()
+    date_str = when.strftime("%Y-%m-%d")
+    document = Document(
+        id=new_document_id(when.date(), NOTES.id_prefix),
+        path=path,
+        title=date_str,
+        type="daily",
+        tags=(),
+        created=timestamp,
+        updated=timestamp,
+    )
+    content = render_frontmatter(document)
+
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        return DailyNote(path=path, document=_read_document(path), created=False)
+
+    with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(content)
+    return DailyNote(path=path, document=document, created=True)