Give it a tool

"""Notes kept under a subject: one file each, in ~/.notes of this sandbox."""

import re
from datetime import datetime
from pathlib import Path

# The store is a directory of its own rather than ~/notes, which ad-hoc work
# in the sandbox already uses: everything this tool writes lives under here
# and nothing else does. The sandbox outlives the runs, so the notes do too.
STORE = Path.home() / ".notes"

# A subject is free text but becomes a filename: letters, digits, spaces,
# dots, dashes and underscores stay, any run of anything else folds to one
# dash. The same rule runs on read and list, so whatever a note was written
# under, it comes back under the same name — and a subject can never climb
# out of the store, because "/" and ".." do not survive it.
_UNSAFE = re.compile(r"[^A-Za-z0-9._ -]+")


def _path(subject: str) -> Path:
    name = _UNSAFE.sub("-", subject).strip().strip(".-")
    name = name[:80].rstrip(" .-")
    if not name:
        raise ValueError(
            "subject cannot be empty: name the note what it is about, e.g. 'terraform state'"
        )
    return STORE / (name + ".md")


def _subjects() -> str:
    if not STORE.exists():
        return ""
    return ", ".join(sorted(path.stem for path in STORE.glob("*.md")))


def write(subject: str, body: str, append: bool = False) -> str:
    """Write a note under a subject — replacing what that subject held, or adding to the end of it with append=true.

    Subjects are free text ("terraform state", "Maria's piano school") and are
    the name the note is read back and listed under, so writing the same
    subject again is an update, not a second note. The body is stored exactly
    as given; markdown is fine.

    Args:
        subject: What the note is about; this is its name everywhere else.
        body: The note itself.
        append: True adds the body to the end of the existing note, after a
            separator, instead of replacing it.
    """
    path = _path(subject)
    path.parent.mkdir(parents=True, exist_ok=True)
    existed = path.exists()
    appending = append and existed
    if appending:
        with path.open("a", encoding="utf-8") as note:
            note.write("\n\n---\n\n" + body)
    else:
        path.write_text(body, encoding="utf-8")
    verb = "appended to" if appending else "replaced" if existed else "wrote"
    return "%s: %s, %d bytes" % (path, verb, path.stat().st_size)


def read(subject: str) -> str:
    """Read a note back whole by its subject — the body exactly as written, or an error naming the subjects that do exist.

    Args:
        subject: The subject the note was written under.
    """
    path = _path(subject)
    if not path.exists():
        have = _subjects()
        raise FileNotFoundError(
            "no note under %r — subjects I have: %s" % (subject, have or "none yet")
        )
    return path.read_text(encoding="utf-8")


# This function shadows the built-in `list` for the rest of the module, which
# is why no other function here annotates or names the type: keep it that way.
def list() -> str:
    """List every note kept on this machine — one line per subject with its size and when it was last written."""
    if not STORE.exists():
        return "no notes yet in %s — write the first with notes__write(subject=..., body=...)" % STORE
    rows = []
    for path in sorted(STORE.glob("*.md"), key=lambda p: p.stat().st_mtime):
        stat = path.stat()
        rows.append(
            "- %s (%d bytes, updated %s)"
            % (path.stem, stat.st_size, datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M"))
        )
    return "%d note%s in %s:\n%s" % (len(rows), "" if len(rows) == 1 else "s", STORE, "\n".join(rows))