endpaper 0.0.1__py3-none-any.whl

endpaper/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

endpaper/__main__.py

@@ -0,0 +1,4 @@
+from endpaper.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

endpaper/cli/main.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+from endpaper import __version__
+from endpaper.cli.output import (
+    print_documents_json,
+    print_documents_table,
+    print_error,
+    print_tasks_json,
+    print_tasks_table,
+    relative_path,
+)
+from endpaper.core.documents import filter_documents
+from endpaper.core.errors import EndpaperError, UsageError, WorkspaceError
+from endpaper.core.meetings import create_meeting, scan_meetings
+from endpaper.core.models import DocumentFilter, TaskFilter
+from endpaper.core.notes import create_note, open_daily_note, scan_notes
+from endpaper.core.tasks import add_task, filter_tasks, load_tasks, set_task_state
+from endpaper.core.workspace import find_workspace, init_workspace
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="endpaper",
+        description="A corporate-friendly Markdown notes engine that makes your AI happy.",
+    )
+    parser.add_argument("--version", action="version", version=f"endpaper {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("init", help="create a workspace in the current directory")
+
+    meeting_parser = subparsers.add_parser("meeting", help="create or list meetings")
+    meeting_subparsers = meeting_parser.add_subparsers(dest="meeting_command", required=True)
+
+    new_parser = meeting_subparsers.add_parser(
+        "new",
+        help="create a meeting",
+        description=(
+            "Create a meeting. NOTE: '#' starts a comment in bash and zsh, so an unquoted "
+            "#tag is silently stripped by the shell before endpaper ever sees it. Use --tag "
+            "instead, or put the #tag inside a quoted description."
+        ),
+    )
+    new_parser.add_argument("description")
+    new_parser.add_argument("--type", default="")
+    new_parser.add_argument(
+        "--tag",
+        action="append",
+        default=[],
+        help="repeatable; the supported way to attach a tag on the command line",
+    )
+
+    list_parser = meeting_subparsers.add_parser("list", help="list meetings")
+    list_parser.add_argument("--json", action="store_true")
+    list_parser.add_argument("--type")
+    list_parser.add_argument("--tag", action="append", default=[])
+    list_parser.add_argument("--since", help="ISO date, e.g. 2026-07-28; inclusive")
+
+    note_parser = subparsers.add_parser("note", help="create or list notes")
+    note_subparsers = note_parser.add_subparsers(dest="note_command", required=True)
+
+    note_subparsers.add_parser("today", help="open (creating if needed) today's daily note")
+
+    note_new_parser = note_subparsers.add_parser(
+        "new",
+        help="create a note",
+        description=(
+            "Create a note. NOTE: '#' starts a comment in bash and zsh, so an unquoted "
+            "#tag is silently stripped by the shell before endpaper ever sees it. Use --tag "
+            "instead, or put the #tag inside a quoted description."
+        ),
+    )
+    note_new_parser.add_argument("description")
+    note_new_parser.add_argument("--type", default="")
+    note_new_parser.add_argument(
+        "--tag",
+        action="append",
+        default=[],
+        help="repeatable; the supported way to attach a tag on the command line",
+    )
+
+    note_list_parser = note_subparsers.add_parser("list", help="list notes")
+    note_list_parser.add_argument("--json", action="store_true")
+    note_list_parser.add_argument("--type")
+    note_list_parser.add_argument("--tag", action="append", default=[])
+    note_list_parser.add_argument("--since", help="ISO date, e.g. 2026-07-28; inclusive")
+
+    task_parser = subparsers.add_parser("task", help="capture, list, and complete tasks")
+    task_subparsers = task_parser.add_subparsers(dest="task_command", required=True)
+
+    task_add_parser = task_subparsers.add_parser(
+        "add",
+        help="capture a task",
+        description=(
+            "Capture a task. NOTE: '#' starts a comment in bash and zsh, so an unquoted "
+            "#tag is silently stripped by the shell before endpaper ever sees it. Use --tag "
+            "instead, or put the #tag inside a quoted description."
+        ),
+    )
+    task_add_parser.add_argument("description")
+    task_add_parser.add_argument("--type", default="")
+    task_add_parser.add_argument(
+        "--tag",
+        action="append",
+        default=[],
+        help="repeatable; the supported way to attach a tag on the command line",
+    )
+
+    task_list_parser = task_subparsers.add_parser("list", help="list tasks")
+    task_list_parser.add_argument("--json", action="store_true")
+    task_list_parser.add_argument("--all", action="store_true", help="include completed tasks")
+    task_list_parser.add_argument("--type")
+    task_list_parser.add_argument("--tag", action="append", default=[])
+
+    task_done_parser = task_subparsers.add_parser("done", help="mark a task complete")
+    task_done_parser.add_argument("id")
+
+    task_undone_parser = task_subparsers.add_parser("undone", help="mark a task incomplete")
+    task_undone_parser.add_argument("id")
+
+    return parser
+
+
+def _run_tui() -> int:
+    if not sys.stdout.isatty():
+        print_error("stdout is not a terminal; refusing to open the interface")
+        return WorkspaceError.exit_code
+
+    try:
+        workspace = find_workspace(Path.cwd())
+    except WorkspaceError as exc:
+        print_error(str(exc))
+        return exc.exit_code
+
+    from endpaper.tui.app import EndpaperApp
+
+    EndpaperApp(workspace).run()
+    return 0
+
+
+_GUIDANCE_ADVICE = {
+    "AGENTS.md": "Add the commands and file format an assistant needs.",
+    "CLAUDE.md": "Add a line telling your assistant to read AGENTS.md.",
+}
+
+
+def _cmd_init() -> int:
+    result = init_workspace(Path.cwd())
+    print(str(result.workspace.root))
+    for name in result.skipped:
+        print(
+            f"note: {name} already exists and was left unchanged.\n      {_GUIDANCE_ADVICE[name]}",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def _parse_since(value: str | None) -> date | None:
+    if not value:
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        raise UsageError(f"--since expects a date like 2026-07-28, got {value!r}") from None
+
+
+def _cmd_meeting_new(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    meeting = create_meeting(
+        workspace,
+        namespace.description,
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+    )
+    print(relative_path(workspace, meeting))
+    return 0
+
+
+def _cmd_meeting_list(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    meetings, warnings = scan_meetings(workspace)
+    for warning in warnings:
+        print_error(warning.message)
+
+    document_filter = DocumentFilter(
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+        since=_parse_since(namespace.since),
+    )
+    filtered = filter_documents(meetings, document_filter)
+
+    if namespace.json:
+        print_documents_json(workspace, filtered)
+    else:
+        print_documents_table(workspace, filtered)
+    return 0
+
+
+def _cmd_note_today() -> int:
+    workspace = find_workspace(Path.cwd())
+    daily = open_daily_note(workspace)
+    print(daily.path.relative_to(workspace.root).as_posix())
+    return 0
+
+
+def _cmd_note_new(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    note = create_note(
+        workspace,
+        namespace.description,
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+    )
+    print(relative_path(workspace, note))
+    return 0
+
+
+def _cmd_note_list(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    notes, warnings = scan_notes(workspace)
+    for warning in warnings:
+        print_error(warning.message)
+
+    document_filter = DocumentFilter(
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+        since=_parse_since(namespace.since),
+    )
+    filtered = filter_documents(notes, document_filter)
+
+    if namespace.json:
+        print_documents_json(workspace, filtered)
+    else:
+        print_documents_table(workspace, filtered)
+    return 0
+
+
+def _cmd_task_add(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    task = add_task(
+        workspace,
+        namespace.description,
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+    )
+    print(task.id)
+    return 0
+
+
+def _cmd_task_list(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    tasks, warnings = load_tasks(workspace)
+    for warning in warnings:
+        print_error(warning.message)
+
+    task_filter = TaskFilter(
+        type=namespace.type,
+        tags=tuple(namespace.tag),
+        include_done=namespace.all,
+    )
+    filtered = filter_tasks(tasks, task_filter)
+
+    if namespace.json:
+        print_tasks_json(filtered)
+    else:
+        print_tasks_table(filtered)
+    return 0
+
+
+def _cmd_task_done(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    set_task_state(workspace, namespace.id, done=True)
+    return 0
+
+
+def _cmd_task_undone(namespace: argparse.Namespace) -> int:
+    workspace = find_workspace(Path.cwd())
+    set_task_state(workspace, namespace.id, done=False)
+    return 0
+
+
+def _dispatch(namespace: argparse.Namespace) -> int:
+    if namespace.command == "init":
+        return _cmd_init()
+    if namespace.command == "meeting":
+        if namespace.meeting_command == "new":
+            return _cmd_meeting_new(namespace)
+        return _cmd_meeting_list(namespace)
+    if namespace.command == "note":
+        if namespace.note_command == "today":
+            return _cmd_note_today()
+        if namespace.note_command == "new":
+            return _cmd_note_new(namespace)
+        return _cmd_note_list(namespace)
+    if namespace.command == "task":
+        if namespace.task_command == "add":
+            return _cmd_task_add(namespace)
+        if namespace.task_command == "done":
+            return _cmd_task_done(namespace)
+        if namespace.task_command == "undone":
+            return _cmd_task_undone(namespace)
+        return _cmd_task_list(namespace)
+    raise UsageError(f"unknown command: {namespace.command}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if not args:
+        return _run_tui()
+
+    parser = _build_parser()
+    try:
+        namespace = parser.parse_args(args)
+    except SystemExit as exc:
+        code = exc.code
+        if isinstance(code, int):
+            return code
+        return 0 if code is None else 1
+
+    try:
+        return _dispatch(namespace)
+    except EndpaperError as exc:
+        print_error(str(exc))
+        return exc.exit_code

endpaper/cli/output.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable
+
+from endpaper.core.models import Document, Task, Workspace
+
+
+def relative_path(workspace: Workspace, document: Document) -> str:
+    return document.path.relative_to(workspace.root).as_posix()
+
+
+def print_document_line(workspace: Workspace, document: Document) -> None:
+    print(
+        "\t".join(
+            [
+                document.created[:10],
+                document.type,
+                document.title,
+                ",".join(document.tags),
+            ]
+        )
+    )
+
+
+def print_documents_table(workspace: Workspace, documents: Iterable[Document]) -> None:
+    for document in documents:
+        print_document_line(workspace, document)
+
+
+def print_documents_json(workspace: Workspace, documents: Iterable[Document]) -> None:
+    records = [
+        {
+            "id": document.id,
+            "path": relative_path(workspace, document),
+            "title": document.title,
+            "type": document.type,
+            "tags": list(document.tags),
+            "created": document.created,
+            "updated": document.updated,
+        }
+        for document in documents
+    ]
+    print(json.dumps(records, ensure_ascii=False))
+
+
+def print_error(message: str) -> None:
+    print(f"endpaper: {message}", file=sys.stderr)
+
+
+def print_task_line(task: Task) -> None:
+    print(
+        "\t".join(
+            [
+                task.id or "",
+                "done" if task.done else "open",
+                task.created.isoformat() if task.created else "-",
+                task.type,
+                task.text,
+                ",".join(task.tags),
+            ]
+        )
+    )
+
+
+def print_tasks_table(tasks: Iterable[Task]) -> None:
+    for task in tasks:
+        print_task_line(task)
+
+
+def print_tasks_json(tasks: Iterable[Task]) -> None:
+    records = [
+        {
+            "id": task.id,
+            "text": task.text,
+            "done": task.done,
+            "type": task.type,
+            "tags": list(task.tags),
+            "created": task.created.isoformat() if task.created else None,
+            "line": task.line,
+        }
+        for task in tasks
+    ]
+    print(json.dumps(records, ensure_ascii=False))

endpaper/core/__init__.py

@@ -0,0 +1,97 @@
+from endpaper.core.documents import (
+    create_document,
+    filter_documents,
+    match_document,
+    scan_documents,
+)
+from endpaper.core.editing import load_for_edit, save_buffer, stamp_updated
+from endpaper.core.errors import EndpaperError, NotFoundError, UsageError, WorkspaceError
+from endpaper.core.frontmatter import read_frontmatter, render_frontmatter
+from endpaper.core.meetings import create_meeting, filter_meetings, match_meeting, scan_meetings
+from endpaper.core.models import (
+    Collection,
+    DailyNote,
+    Document,
+    DocumentFilter,
+    EditableFile,
+    InitResult,
+    Meeting,
+    MeetingFilter,
+    Note,
+    ParsedTasks,
+    SaveResult,
+    ScanWarning,
+    Task,
+    TaskFilter,
+    Workspace,
+)
+from endpaper.core.notes import create_note, open_daily_note, scan_notes
+from endpaper.core.tasks import (
+    add_task,
+    filter_tasks,
+    load_tasks,
+    match_task,
+    parse_tasks,
+    render_task_line,
+    set_task_state,
+)
+from endpaper.core.text import (
+    new_document_id,
+    new_meeting_id,
+    new_task_id,
+    parse_tags,
+    slugify,
+)
+from endpaper.core.workspace import find_workspace, init_workspace
+
+__all__ = [
+    "Collection",
+    "DailyNote",
+    "Document",
+    "DocumentFilter",
+    "EditableFile",
+    "EndpaperError",
+    "InitResult",
+    "Meeting",
+    "MeetingFilter",
+    "Note",
+    "NotFoundError",
+    "ParsedTasks",
+    "SaveResult",
+    "ScanWarning",
+    "Task",
+    "TaskFilter",
+    "UsageError",
+    "Workspace",
+    "WorkspaceError",
+    "add_task",
+    "create_document",
+    "create_meeting",
+    "create_note",
+    "filter_documents",
+    "filter_meetings",
+    "filter_tasks",
+    "find_workspace",
+    "init_workspace",
+    "load_for_edit",
+    "load_tasks",
+    "match_document",
+    "match_meeting",
+    "match_task",
+    "new_document_id",
+    "new_meeting_id",
+    "new_task_id",
+    "open_daily_note",
+    "parse_tags",
+    "parse_tasks",
+    "read_frontmatter",
+    "render_frontmatter",
+    "render_task_line",
+    "save_buffer",
+    "scan_documents",
+    "scan_meetings",
+    "scan_notes",
+    "set_task_state",
+    "slugify",
+    "stamp_updated",
+]

endpaper/core/documents.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import replace
+from datetime import date, datetime
+from pathlib import Path
+
+from endpaper.core.errors import UsageError
+from endpaper.core.frontmatter import FrontmatterError, read_frontmatter, render_frontmatter
+from endpaper.core.models import Collection, Document, DocumentFilter, ScanWarning, Workspace
+from endpaper.core.text import new_document_id, parse_tags, slugify
+
+_TOKEN_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$")
+
+
+def _validate_token(value: str, flag: str) -> str:
+    if not _TOKEN_PATTERN.match(value):
+        raise UsageError(f"--{flag} may not contain '/', '\\', '.', or start with '-'")
+    return value.lower()
+
+
+def create_document(
+    workspace: Workspace,
+    collection: Collection,
+    description: str,
+    *,
+    type: str = "",
+    tags: Sequence[str] = (),
+    now: datetime | None = None,
+) -> Document:
+    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 ""
+    if normalized_type in collection.reserved_types:
+        raise UsageError(
+            f"type '{normalized_type}' is reserved; use 'endpaper note today' for the daily note"
+        )
+
+    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)
+
+    document_id = new_document_id(when.date(), collection.id_prefix)
+    timestamp = when.replace(microsecond=0).isoformat()
+    slug = slugify(title)
+    date_str = when.strftime("%Y-%m-%d")
+    stem = "-".join([date_str, *([normalized_type] if normalized_type else []), slug])
+
+    create_dir = workspace.root / collection.create_dir / f"{when:%Y/%m}"
+    create_dir.mkdir(parents=True, exist_ok=True)
+
+    partial = Document(
+        id=document_id,
+        path=create_dir / f"{stem}.md",
+        title=title,
+        type=normalized_type,
+        tags=tuple(merged_tags),
+        created=timestamp,
+        updated=timestamp,
+    )
+    content = render_frontmatter(partial)
+
+    suffix = 1
+    while True:
+        filename = f"{stem}.md" if suffix == 1 else f"{stem}-{suffix}.md"
+        candidate = create_dir / filename
+        try:
+            fd = os.open(candidate, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            suffix += 1
+            continue
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(content)
+        return replace(partial, path=candidate)
+
+
+def _parse_document(text: str, path: Path) -> tuple[Document | None, ScanWarning | None]:
+    """Parse one file's already-read text. Returns (document, None) on success or
+    (None, warning) on any structural problem -- never raises."""
+    if not text.startswith("---\n"):
+        return None, ScanWarning(
+            path=path,
+            reason="no_frontmatter",
+            message=f"{path.name}: does not start with a frontmatter block",
+        )
+
+    terminator = text.find("\n---", 3)
+    if terminator == -1:
+        return None, ScanWarning(
+            path=path,
+            reason="unterminated_frontmatter",
+            message=f"{path.name}: frontmatter block is never terminated",
+        )
+
+    block = text[4 : terminator + 1]
+    try:
+        data = read_frontmatter(block)
+    except FrontmatterError as exc:
+        return None, ScanWarning(
+            path=path, reason=exc.reason, message=f"{path.name}: {exc.message}"
+        )
+
+    type_value = str(data["type"])
+    tag_values = [str(t) for t in data["tags"]]
+
+    if type_value and not _TOKEN_PATTERN.match(type_value):
+        return None, ScanWarning(
+            path=path, reason="invalid_value", message=f"{path.name}: invalid type {type_value!r}"
+        )
+    if any(not _TOKEN_PATTERN.match(tag) for tag in tag_values):
+        return None, ScanWarning(
+            path=path,
+            reason="invalid_value",
+            message=f"{path.name}: invalid tag in {tag_values!r}",
+        )
+
+    document = Document(
+        id=str(data["id"]),
+        path=path,
+        title=str(data["title"]),
+        type=type_value,
+        tags=tuple(tag_values),
+        created=str(data["created"]),
+        updated=str(data["updated"]),
+    )
+    return document, None
+
+
+def _read_document(path: Path) -> Document | None:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    document, _ = _parse_document(text, path)
+    return document
+
+
+def scan_documents(
+    workspace: Workspace,
+    collection: Collection,
+) -> tuple[list[Document], list[ScanWarning]]:
+    documents: list[Document] = []
+    warnings: list[ScanWarning] = []
+
+    for scan_dir in collection.scan_dirs:
+        directory = workspace.root / scan_dir
+        if not directory.is_dir():
+            continue
+
+        for path in sorted(directory.rglob("*.md")):
+            text = path.read_text(encoding="utf-8", errors="replace")
+            document, warning = _parse_document(text, path)
+            if document is not None:
+                documents.append(document)
+            else:
+                assert warning is not None
+                warnings.append(warning)
+
+    documents.sort(key=lambda d: str(d.path))
+    documents.sort(key=lambda d: d.created, reverse=True)
+    return documents, warnings
+
+
+def filter_documents(documents: Iterable[Document], f: DocumentFilter) -> list[Document]:
+    results: list[Document] = []
+    for document in documents:
+        if f.type is not None and document.type.lower() != f.type.lower():
+            continue
+        if f.tags:
+            document_tags = {tag.lower() for tag in document.tags}
+            if not all(tag.lower() in document_tags for tag in f.tags):
+                continue
+        if f.since is not None:
+            created_date = date.fromisoformat(document.created[:10])
+            if created_date < f.since:
+                continue
+        results.append(document)
+    return results
+
+
+def match_document(document: Document, query: str) -> bool:
+    haystack = " ".join([document.title, document.type, *document.tags]).lower()
+    return query.lower() in haystack