duras 1.0.0__py3-none-any.whl

duras/__init__.py

@@ -0,0 +1 @@
+from .core import VERSION

duras/cli.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+#
+# duras — daily notes as plain text files, with search and optional encryption.
+# No external dependencies (GnuPG optional for confidential notes).
+#
+# Copyright (c) 2026 Sergiy Duras
+# SPDX-License-Identifier: ISC
+
+import argparse
+import sys
+
+from .core import (
+    VERSION,
+    DurasError,
+    DurasExternalError,
+    DurasInputError,
+    DurasNotFoundError,
+    _ensure_notes_dir_perms,
+    _parse_date_strict,
+    cmd_append,
+    cmd_audit,
+    cmd_dir,
+    cmd_echo,
+    cmd_export,
+    cmd_list,
+    cmd_mv,
+    cmd_near,
+    cmd_open,
+    cmd_path,
+    cmd_search,
+    cmd_show,
+    cmd_stats,
+    cmd_tags,
+    cmd_today,
+    parse_date,
+    today,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="duras",
+        description="plain-text daily notes with optional encryption",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+SUBCOMMANDS
+  open [DATE] [-- ARGS]   Open note in $EDITOR; pass ARGS after --
+  append [-d DATE] TEXT   Append timestamped line; "-" reads stdin
+  show [DATE]             Print note to stdout
+  list [-n N]             List recent notes (default: 10, 0 = all)
+  search KEYWORD [-i]     Search plain notes (literal, -i = ignore case)
+  tags [TAG]              List all #tags or notes containing #TAG
+  stats                   Show counts, size, date range, streak
+  export [DIR] [--encrypt] Archive notes to tar.gz (optionally GPG)
+  path [DATE]             Print absolute note path
+  dir                     Print notes root directory
+  today                   Print today's date (YYYY-MM-DD)
+  audit                   Validate notes directory structure
+  echo [DATE]             List notes sharing the same MM-DD across years
+  near [DATE]             List notes within ±3 days of a date
+  mv FROM TO              Move a note from one date to another (YYYY-MM-DD only)
+
+DATE FORMATS
+  YYYY-MM-DD              Absolute date (e.g. 2026-01-15)
+  INTEGER                 Relative offset: 0 (today), -1 (yesterday)
+
+ENVIRONMENT
+  DURAS_DIR                Notes directory (default: ~/Documents/Notes)
+  EDITOR                  Editor (fallback: nano, vi, ed)
+  DURAS_GPG_KEY            GPG recipient (default: self)
+
+COMMON WORKFLOWS
+  duras                    Open today's note
+  duras open -1            Open yesterday's note
+  duras open -- +10        Open note and jump to line 10 in editor
+
+  duras append "note"      Append to today
+  duras append -d -1 "x"   Append to yesterday
+  cat file.txt | duras append -   Append stdin
+
+  duras -c open            Open encrypted note
+  duras -c append "secret" Append encrypted entry
+  duras show -c            Show encrypted note
+
+  duras list               Show recent notes
+  duras list -n 0          Show all notes
+
+  duras search "error"     Search notes
+  duras search "todo" -i   Case-insensitive search
+
+  duras tags               List all tags
+  duras tags project       Notes with #project
+
+  duras export ~/backup            Create archive
+  duras export ~/backup --encrypt  Encrypted archive
+
+  duras audit              Verify notes directory is structurally clean
+
+  duras echo               List past notes on today's date in history
+  duras echo 2026-03-15    List past notes on March 15 across all years
+  duras near               List notes within ±3 days of today
+  duras near 2026-01-01    List notes around a specific date
+
+  duras mv 2026-04-17 2026-04-16   Move a misdated note (YYYY-MM-DD only)
+
+NOTES
+  Files are plain text (.dn); encrypted notes use .dn.gpg
+  Encrypted notes are skipped by search and tags
+
+EXIT CODES
+  0  Success
+  1  Generic error
+  2  Not found
+  3  Invalid input
+  4  External tool failure
+
+Documentation:
+  https://codeberg.org/duras/duras
+""",
+    )
+    p.add_argument("--version", action="version", version=f"duras {VERSION}")
+    p.add_argument(
+        "-c",
+        "--confidential",
+        action="store_true",
+        help="use gpg encryption for this note",
+    )
+
+    sub = p.add_subparsers(dest="cmd")
+
+    p_open = sub.add_parser("open", help="open note in $EDITOR")
+    p_open.add_argument(
+        "date", nargs="?", help="YYYY-MM-DD or offset (default: 0)"
+    )
+    p_open.add_argument(
+        "extra",
+        nargs=argparse.REMAINDER,
+        help="args passed to $EDITOR (after --)",
+    )
+
+    p_app = sub.add_parser("append", help="append text without editor")
+    p_app.add_argument(
+        "-d", "--date", dest="date", help="YYYY-MM-DD or offset (default: 0)"
+    )
+    p_app.add_argument("text", help="text to append or '-' for stdin")
+
+    p_show = sub.add_parser("show", help="print note to stdout")
+    p_show.add_argument(
+        "date", nargs="?", help="YYYY-MM-DD or offset (default: 0)"
+    )
+
+    p_list = sub.add_parser("list", help="list recent notes")
+    p_list.add_argument(
+        "-n",
+        "--count",
+        type=int,
+        default=10,
+        metavar="N",
+        help="notes to show (0 = all)",
+    )
+
+    p_search = sub.add_parser("search", help="search notes for keyword")
+    p_search.add_argument("keyword", help="text to search for")
+    p_search.add_argument(
+        "-i",
+        "--ignore-case",
+        action="store_true",
+        help="case-insensitive search",
+    )
+
+    p_tags = sub.add_parser("tags", help="list all #tags (or notes for a tag)")
+    p_tags.add_argument(
+        "tag", nargs="?", default="", help="#TAG to filter by (optional)"
+    )
+
+    sub.add_parser("stats", help="show note counts, size, and streak")
+
+    p_export = sub.add_parser("export", help="archive notes to tar.gz")
+    p_export.add_argument(
+        "dest",
+        nargs="?",
+        default=".",
+        help="destination directory (default: .)",
+    )
+    p_export.add_argument(
+        "--encrypt", action="store_true", help="encrypt the archive with gpg"
+    )
+
+    p_path = sub.add_parser("path", help="print note file path")
+    p_path.add_argument(
+        "date", nargs="?", help="YYYY-MM-DD or offset (default: 0)"
+    )
+
+    sub.add_parser("dir", help="print notes directory")
+    sub.add_parser("today", help="print today's date")
+    sub.add_parser("audit", help="validate notes directory structure")
+
+    p_echo = sub.add_parser(
+        "echo", help="list notes sharing the same MM-DD across years"
+    )
+    p_echo.add_argument(
+        "date", nargs="?", help="YYYY-MM-DD or offset (default: today)"
+    )
+
+    p_near = sub.add_parser("near", help="list notes within ±3 days of a date")
+    p_near.add_argument(
+        "date", nargs="?", help="YYYY-MM-DD or offset (default: today)"
+    )
+
+    p_mv = sub.add_parser("mv", help="move a note from one date to another")
+    p_mv.add_argument(
+        "old_date", metavar="FROM", help="source date (YYYY-MM-DD)"
+    )
+    p_mv.add_argument(
+        "new_date", metavar="TO", help="destination date (YYYY-MM-DD)"
+    )
+
+    return p
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    confidential = args.confidential
+
+    _ensure_notes_dir_perms()
+
+    try:
+        if args.cmd is None:
+            extra_args = []
+            if "--" in argv:
+                split = argv.index("--")
+                extra_args = argv[split + 1 :]
+            cmd_open(today(), confidential, extra_args)
+
+        elif args.cmd == "open":
+            date = parse_date(args.date) if args.date else today()
+            ea = [a for a in (args.extra or []) if a != "--"]
+            cmd_open(date, confidential, ea)
+
+        elif args.cmd == "append":
+            date = parse_date(args.date) if args.date else today()
+            if args.text == "-":
+                text = sys.stdin.read().rstrip("\n")
+                if not text:
+                    raise DurasInputError("no text read from stdin")
+            else:
+                text = args.text
+            cmd_append(date, text, confidential)
+
+        elif args.cmd == "show":
+            date = parse_date(args.date) if args.date else today()
+            cmd_show(date, confidential)
+
+        elif args.cmd == "list":
+            cmd_list(args.count)
+
+        elif args.cmd == "search":
+            cmd_search(args.keyword, args.ignore_case)
+
+        elif args.cmd == "tags":
+            cmd_tags(args.tag)
+
+        elif args.cmd == "stats":
+            cmd_stats()
+
+        elif args.cmd == "export":
+            cmd_export(args.dest, args.encrypt)
+
+        elif args.cmd == "path":
+            date = parse_date(args.date) if args.date else today()
+            cmd_path(date, confidential)
+
+        elif args.cmd == "dir":
+            cmd_dir()
+
+        elif args.cmd == "today":
+            cmd_today()
+
+        elif args.cmd == "audit":
+            count = cmd_audit()
+            if count:
+                sys.exit(1)
+
+        elif args.cmd == "echo":
+            date = parse_date(args.date) if args.date else today()
+            cmd_echo(date)
+
+        elif args.cmd == "near":
+            date = parse_date(args.date) if args.date else today()
+            cmd_near(date)
+
+        elif args.cmd == "mv":
+            old_date = _parse_date_strict(args.old_date)
+            new_date = _parse_date_strict(args.new_date)
+            cmd_mv(old_date, new_date)
+
+        else:
+            parser.print_help()
+            sys.exit(1)
+
+    except DurasError as e:
+        print(f"duras: {e}", file=sys.stderr)
+        sys.exit(e.exit_code)
+
+
+if __name__ == "__main__":
+    main()

duras/core.py

@@ -0,0 +1,813 @@
+#!/usr/bin/env python3
+#
+# duras — daily notes as plain text files, with search and optional encryption.
+# core library: all domain logic. Imported by cli.py.
+#
+# Copyright (c) 2026 Sergiy Duras
+# SPDX-License-Identifier: ISC
+
+import datetime
+import io
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from typing import Optional
+
+VERSION = "1.0.0"
+
+DEFAULT_NOTES_DIR = os.path.join(os.path.expanduser("~"), "Documents", "Notes")
+NOTE_EXT = ".dn"
+ENC_EXT = ".dn.gpg"
+DATE_FMT = "%Y-%m-%d"
+DATETIME_FMT = "%Y-%m-%d %H:%M"
+
+
+class DurasError(Exception):
+    """Raised by core on any recoverable user-facing error."""
+
+    exit_code = 1
+
+
+class DurasNotFoundError(DurasError):
+    """Note or directory not found. exit_code=2."""
+
+    exit_code = 2
+
+
+class DurasInputError(DurasError):
+    """Invalid user input (bad date, wrong flag, etc.). exit_code=3."""
+
+    exit_code = 3
+
+
+class DurasExternalError(DurasError):
+    """External tool failure (gpg, editor). exit_code=4."""
+
+    exit_code = 4
+
+
+def warn(msg: str) -> None:
+    print(f"duras: warning: {msg}", file=sys.stderr)
+
+
+def notes_dir() -> str:
+    d = os.environ.get("DURAS_DIR", DEFAULT_NOTES_DIR)
+    return os.path.abspath(os.path.expanduser(d))
+
+
+def editor() -> list[str]:
+    ed = os.environ.get("EDITOR")
+    if ed:
+        return shlex.split(ed)
+
+    for candidate in ("nano", "vi", "ed"):
+        if shutil.which(candidate):
+            return [candidate]
+
+    raise DurasExternalError("no editor found: set $EDITOR")
+
+
+def gpg_key() -> str:
+    return os.environ.get("DURAS_GPG_KEY") or ""
+
+
+def today() -> datetime.date:
+    return datetime.date.today()
+
+
+def parse_date(s: str) -> datetime.date:
+    try:
+        return datetime.datetime.strptime(s, DATE_FMT).date()
+    except ValueError:
+        pass
+    try:
+        return today() + datetime.timedelta(days=int(s))
+    except ValueError:
+        raise DurasInputError(
+            f"invalid date '{s}' — expected YYYY-MM-DD or integer offset (e.g. -1, 0, 7)"
+        )
+
+
+def note_path(date: datetime.date, confidential: bool = False) -> str:
+    ext = ENC_EXT if confidential else NOTE_EXT
+    d = notes_dir()
+    return os.path.join(
+        d,
+        f"{date.year:04d}",
+        f"{date.month:02d}",
+        f"{date.strftime(DATE_FMT)}{ext}",
+    )
+
+
+def all_note_files() -> list[str]:
+    d = notes_dir()
+    found: list[str] = []
+    if not os.path.isdir(d):
+        return found
+    for root, _, files in os.walk(d):
+        for name in files:
+            if name.endswith(NOTE_EXT) or name.endswith(ENC_EXT):
+                found.append(os.path.join(root, name))
+    found.sort(key=os.path.basename)
+    return found
+
+
+def _is_broken_symlink(entry: "os.DirEntry[str]") -> bool:
+    return entry.is_symlink() and not os.path.exists(entry.path)
+
+
+def _parse_note_filename(
+    name: str,
+) -> tuple[Optional[datetime.date], str]:
+    if name.endswith(ENC_EXT):
+        stem = name[: -len(ENC_EXT)]
+    elif name.endswith(NOTE_EXT):
+        stem = name[: -len(NOTE_EXT)]
+    else:
+        return None, "not a .dn or .dn.gpg file"
+    try:
+        return datetime.datetime.strptime(stem, DATE_FMT).date(), ""
+    except ValueError:
+        return None, f"filename date {stem!r} is not a valid YYYY-MM-DD date"
+
+
+def _header_lines(date: datetime.date, is_today: bool) -> int:
+    return 3
+
+
+def ensure_dir(path: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+
+
+def _ensure_notes_dir_perms() -> None:
+    d = notes_dir()
+    try:
+        os.makedirs(d, exist_ok=True)
+        mode = os.stat(d).st_mode & 0o777
+        if mode & 0o077:
+            os.chmod(d, 0o700)
+    except OSError:
+        pass
+
+
+def _secure_tmpdir() -> str:
+    shm = "/dev/shm"
+    if os.path.isdir(shm) and os.access(shm, os.W_OK):
+        try:
+            return tempfile.mkdtemp(dir=shm, prefix="duras-")
+        except OSError:
+            pass
+    return tempfile.mkdtemp(prefix="duras-")
+
+
+def atomic_write(path: str, content: str) -> None:
+    dir_ = os.path.dirname(path)
+    os.makedirs(dir_, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dir_, prefix=".duras-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+        dir_fd = os.open(dir_, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_bytes(path: str, data: bytes) -> None:
+    dir_ = os.path.dirname(path)
+    os.makedirs(dir_, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dir_, prefix=".duras-")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+        dir_fd = os.open(dir_, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def note_header(date: datetime.date, is_today: bool = True) -> str:
+    now = datetime.datetime.now()
+    if is_today:
+        return f"{date.strftime(DATE_FMT)}\n{now.strftime('%H:%M')}\n\n"
+    return (
+        f"{date.strftime(DATE_FMT)}\ncreated: {now.strftime(DATETIME_FMT)}\n\n"
+    )
+
+
+def init_note(path: str, date: datetime.date, is_today: bool = True) -> None:
+    atomic_write(path, note_header(date, is_today))
+
+
+def append_text(path: str, text: str) -> None:
+    now = datetime.datetime.now().strftime(DATETIME_FMT)
+    line = f"[{now}] {text}\n"
+    existing = ""
+    if os.path.exists(path):
+        try:
+            with open(path, encoding="utf-8", errors="strict") as f:
+                existing = f.read()
+        except UnicodeDecodeError as e:
+            raise DurasError(
+                f"note is not valid UTF-8, will not append: {path}: {e}"
+            )
+    if existing and not existing.endswith("\n"):
+        existing += "\n"
+    atomic_write(path, existing + line)
+
+
+def open_in_editor(path: str, extra_args: Optional[list[str]] = None) -> None:
+    args = editor() + (extra_args or []) + [path]
+    try:
+        result = subprocess.run(args)
+    except FileNotFoundError:
+        raise DurasExternalError(
+            f"editor not found: {args[0]!r} — set $EDITOR"
+        )
+    if result.returncode != 0:
+        raise DurasExternalError(
+            f"editor exited with status {result.returncode}"
+        )
+
+
+def gpg_encrypt(plaintext: bytes, dest: str) -> None:
+    key = gpg_key()
+    dir_ = os.path.dirname(dest) or "."
+    os.makedirs(dir_, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dir_, prefix=".duras-")
+    try:
+        os.close(fd)
+        cmd = ["gpg", "--batch", "--yes", "--quiet", "--output", tmp]
+        if key:
+            cmd += ["--recipient", key, "--encrypt"]
+        else:
+            cmd += ["--default-recipient-self", "--encrypt"]
+        result = subprocess.run(cmd, input=plaintext, capture_output=True)
+        if result.returncode != 0:
+            raise DurasExternalError(
+                f"gpg encryption failed: {result.stderr.decode(errors='replace').strip()}"
+            )
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, dest)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def gpg_decrypt(path: str) -> bytes:
+    result = subprocess.run(
+        ["gpg", "--batch", "--quiet", "--decrypt", path],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        raise DurasExternalError(
+            f"gpg decryption failed: {result.stderr.decode(errors='replace').strip()}"
+        )
+    return result.stdout
+
+
+def open_confidential_in_editor(
+    enc_path: str,
+    date: datetime.date,
+    extra_args: Optional[list[str]] = None,
+    is_today: bool = True,
+) -> None:
+    tmp_dir = _secure_tmpdir()
+    tmp_path = os.path.join(tmp_dir, f"{date.strftime(DATE_FMT)}.dn")
+    try:
+        plaintext = (
+            gpg_decrypt(enc_path)
+            if os.path.exists(enc_path)
+            else note_header(date, is_today).encode("utf-8")
+        )
+        with open(tmp_path, "wb") as f:
+            f.write(plaintext)
+        os.chmod(tmp_path, 0o600)
+
+        open_in_editor(tmp_path, extra_args)
+
+        with open(tmp_path, "rb") as f:
+            new_plaintext = f.read()
+        ensure_dir(enc_path)
+        gpg_encrypt(new_plaintext, enc_path)
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        try:
+            os.rmdir(tmp_dir)
+        except OSError:
+            pass
+
+
+def cmd_open(
+    date: datetime.date, confidential: bool, extra_args: list[str]
+) -> None:
+    is_today = date == today()
+    if date > today():
+        raise DurasInputError(
+            f"cannot open a note for a future date: {date.strftime(DATE_FMT)}"
+        )
+    if confidential:
+        enc_path = note_path(date, confidential=True)
+        ensure_dir(enc_path)
+        open_confidential_in_editor(enc_path, date, extra_args, is_today)
+    else:
+        path = note_path(date)
+        ensure_dir(path)
+        is_new = not os.path.exists(path)
+        if is_new:
+            init_note(path, date, is_today)
+        ea = extra_args or (
+            ["+" + str(_header_lines(date, is_today) + 1)] if is_new else []
+        )
+        open_in_editor(path, ea)
+
+
+def cmd_append_confidential(date: datetime.date, text: str) -> None:
+    enc_path = note_path(date, confidential=True)
+    is_today = date == today()
+    now = datetime.datetime.now().strftime(DATETIME_FMT)
+    line = f"[{now}] {text}\n"
+    if os.path.exists(enc_path):
+        existing = gpg_decrypt(enc_path).decode("utf-8", errors="replace")
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+        new_content = existing + line
+    else:
+        ensure_dir(enc_path)
+        new_content = note_header(date, is_today) + line
+    gpg_encrypt(new_content.encode("utf-8"), enc_path)
+
+
+def cmd_append(
+    date: datetime.date, text: str, confidential: bool = False
+) -> None:
+    if date > today():
+        raise DurasInputError(
+            f"cannot append to a future date: {date.strftime(DATE_FMT)}"
+        )
+    if confidential:
+        cmd_append_confidential(date, text)
+        return
+    is_today = date == today()
+    path = note_path(date)
+    ensure_dir(path)
+    if not os.path.exists(path):
+        init_note(path, date, is_today)
+    append_text(path, text)
+
+
+def cmd_show(date: datetime.date, confidential: bool = False) -> None:
+    plain = note_path(date)
+    enc = note_path(date, confidential=True)
+    plain_exists = os.path.exists(plain)
+    enc_exists = os.path.exists(enc)
+    if confidential:
+        if enc_exists:
+            data = gpg_decrypt(enc)
+            sys.stdout.buffer.write(data)
+        elif plain_exists:
+            raise DurasInputError(
+                f"no encrypted note for {date.strftime(DATE_FMT)} (plain note exists; omit -c)"
+            )
+        else:
+            raise DurasNotFoundError(f"no note for {date.strftime(DATE_FMT)}")
+    else:
+        if plain_exists:
+            if enc_exists:
+                warn(
+                    "both plain and encrypted notes exist for this date; showing plain (use -c for encrypted)"
+                )
+            try:
+                with open(plain, encoding="utf-8", errors="strict") as f:
+                    sys.stdout.write(f.read())
+            except UnicodeDecodeError as e:
+                raise DurasError(f"note is not valid UTF-8: {plain}: {e}")
+        elif enc_exists:
+            raise DurasInputError(
+                "only encrypted note exists for this date; use -c to decrypt"
+            )
+        else:
+            raise DurasNotFoundError(f"no note for {date.strftime(DATE_FMT)}")
+
+
+def cmd_list(count: int) -> None:
+    files = all_note_files()
+    if not files:
+        print("no notes found")
+        return
+    shown = files[-count:] if count > 0 else files
+    for path in reversed(shown):
+        size = os.path.getsize(path)
+        mtime = datetime.datetime.fromtimestamp(os.path.getmtime(path))
+        name = os.path.basename(path)
+        enc = " ⚿" if path.endswith(".gpg") else ""
+        print(
+            f"· {mtime.strftime('%Y-%m-%d %H:%M')} {size/1024:>5.1f}KB  {name}{enc}"
+        )
+
+
+def cmd_search(keyword: str, ignore_case: bool = False) -> None:
+    flags = re.IGNORECASE if ignore_case else 0
+    rx = re.compile(re.escape(keyword), flags)
+    skipped = 0
+    found = False
+    for path in all_note_files():
+        if path.endswith(".gpg"):
+            skipped += 1
+            continue
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                file_matches: list[tuple[int, str]] = []
+                for lineno, line in enumerate(f, 1):
+                    if rx.search(line):
+                        file_matches.append((lineno, line.rstrip()))
+        except OSError as e:
+            warn(f"cannot read {path}: {e}")
+            continue
+        if file_matches:
+            found = True
+            print(path)
+            for lineno, line in file_matches:
+                print(f"  {lineno}: {line}")
+    if skipped:
+        warn(f"{skipped} encrypted note(s) not searched")
+    if not found:
+        print(f"no matches for '{keyword}'")
+
+
+def cmd_tags(tag: str = "") -> None:
+    tag_rx = re.compile(r"#([A-Za-z0-9_-]+)")
+    if tag:
+        needle = tag.lstrip("#").lower()
+        skipped = 0
+        found = False
+        for path in all_note_files():
+            if path.endswith(".gpg"):
+                skipped += 1
+                continue
+            try:
+                with open(path, encoding="utf-8", errors="replace") as f:
+                    for line in f:
+                        if any(
+                            m.group(1).lower() == needle
+                            for m in tag_rx.finditer(line)
+                        ):
+                            print(path)
+                            found = True
+                            break
+            except OSError as e:
+                warn(f"cannot read {path}: {e}")
+        if skipped:
+            warn(f"{skipped} encrypted note(s) not searched")
+        if not found:
+            print(f"no notes tagged #{needle}")
+        return
+    tags: dict[str, int] = {}
+    skipped = 0
+    for path in all_note_files():
+        if path.endswith(".gpg"):
+            skipped += 1
+            continue
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    for m in tag_rx.finditer(line):
+                        t = m.group(1).lower()
+                        tags[t] = tags.get(t, 0) + 1
+        except OSError as e:
+            warn(f"cannot read {path}: {e}")
+    if skipped:
+        warn(f"{skipped} encrypted note(s) not searched")
+    if not tags:
+        print("no tags found")
+        return
+    width = max(len(t) for t in tags)
+    for t, count in sorted(tags.items()):
+        print(f"#{t:<{width}}  {count}")
+
+
+def cmd_stats() -> None:
+    files = all_note_files()
+    if not files:
+        print("no notes found")
+        return
+    total_size = sum(os.path.getsize(p) for p in files)
+    plain = [p for p in files if not p.endswith(".gpg")]
+    enc = [p for p in files if p.endswith(".gpg")]
+    date_rx = re.compile(r"(\d{4}-\d{2}-\d{2})\.dn")
+    dates: set[datetime.date] = set()
+    for p in files:
+        m = date_rx.search(os.path.basename(p))
+        if m:
+            try:
+                dates.add(datetime.date.fromisoformat(m.group(1)))
+            except ValueError:
+                pass
+    streak = 0
+    if dates:
+        check = today()
+        while check in dates:
+            streak += 1
+            check -= datetime.timedelta(days=1)
+    oldest = min(dates).isoformat() if dates else "—"
+    newest = max(dates).isoformat() if dates else "—"
+    print(
+        f"notes:   {len(plain)} plain, {len(enc)} encrypted ({len(files)} total)"
+    )
+    print(f"size:    {total_size / 1024:.1f} KB")
+    print(f"range:   {oldest} — {newest}")
+    print(f"streak:  {streak} day(s)")
+
+
+def cmd_export(dest_dir: str, encrypt: bool) -> None:
+    d = notes_dir()
+    if not os.path.isdir(d):
+        raise DurasNotFoundError(f"notes directory not found: {d}")
+    stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    try:
+        os.makedirs(dest_dir, exist_ok=True)
+    except OSError as e:
+        raise DurasError(f"cannot create destination directory: {e}")
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        tar.add(d, arcname="notes")
+    archive_bytes = buf.getvalue()
+    buf.close()
+
+    if encrypt:
+        dest = os.path.join(dest_dir, f"duras-{stamp}.tar.gz.gpg")
+        dir_ = os.path.dirname(os.path.abspath(dest))
+        fd, tmp = tempfile.mkstemp(dir=dir_, prefix=".duras-export-")
+        try:
+            os.close(fd)
+            key = gpg_key()
+            cmd = ["gpg", "--batch", "--yes", "--quiet", "--output", tmp]
+            if key:
+                cmd += ["--recipient", key, "--encrypt"]
+            else:
+                cmd += ["--default-recipient-self", "--encrypt"]
+            result = subprocess.run(
+                cmd, input=archive_bytes, capture_output=True
+            )
+            if result.returncode != 0:
+                raise DurasExternalError(
+                    f"gpg encryption of archive failed: {result.stderr.decode(errors='replace').strip()}"
+                )
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, dest)
+        except DurasError:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+        except Exception as e:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise DurasError(f"export failed: {e}")
+    else:
+        dest = os.path.join(dest_dir, f"duras-{stamp}.tar.gz")
+        dir_ = os.path.dirname(os.path.abspath(dest))
+        fd, tmp = tempfile.mkstemp(dir=dir_, prefix=".duras-export-")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(archive_bytes)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, dest)
+        except Exception as e:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise DurasError(f"export failed: {e}")
+
+    print(dest)
+
+
+def cmd_path(date: datetime.date, confidential: bool) -> None:
+    print(note_path(date, confidential))
+
+
+def cmd_dir() -> None:
+    print(notes_dir())
+
+
+def cmd_today() -> None:
+    print(today().strftime(DATE_FMT))
+
+
+def cmd_audit() -> int:
+    d = notes_dir()
+    if not os.path.isdir(d):
+        print("notes directory does not exist; nothing to audit")
+        return 0
+
+    issues: list[str] = []
+    seen_plain: set[datetime.date] = set()
+    seen_enc: set[datetime.date] = set()
+
+    try:
+        root_entries = sorted(os.scandir(d), key=lambda e: e.name)
+    except OSError as e:
+        raise DurasError(f"cannot read notes directory: {e}")
+
+    for year_entry in root_entries:
+        if _is_broken_symlink(year_entry):
+            issues.append(f"broken symlink: {year_entry.path}")
+            continue
+        if not year_entry.is_dir(follow_symlinks=False):
+            issues.append(f"unexpected file at notes root: {year_entry.path}")
+            continue
+        if not re.fullmatch(r"\d{4}", year_entry.name):
+            issues.append(
+                f"unexpected directory at notes root: {year_entry.path}"
+            )
+            continue
+        year = int(year_entry.name)
+
+        try:
+            month_entries = sorted(
+                os.scandir(year_entry.path), key=lambda e: e.name
+            )
+        except OSError as e:
+            raise DurasError(f"cannot read directory: {e}")
+
+        for month_entry in month_entries:
+            if _is_broken_symlink(month_entry):
+                issues.append(f"broken symlink: {month_entry.path}")
+                continue
+            if not month_entry.is_dir(follow_symlinks=False):
+                issues.append(
+                    f"unexpected file in year directory: {month_entry.path}"
+                )
+                continue
+            if not re.fullmatch(r"\d{2}", month_entry.name):
+                issues.append(
+                    f"unexpected directory in year directory: {month_entry.path}"
+                )
+                continue
+            month = int(month_entry.name)
+            if not 1 <= month <= 12:
+                issues.append(f"invalid month directory: {month_entry.path}")
+                continue
+
+            try:
+                file_entries = sorted(
+                    os.scandir(month_entry.path), key=lambda e: e.name
+                )
+            except OSError as e:
+                raise DurasError(f"cannot read directory: {e}")
+
+            for file_entry in file_entries:
+                if _is_broken_symlink(file_entry):
+                    issues.append(f"broken symlink: {file_entry.path}")
+                    continue
+                if file_entry.is_dir(follow_symlinks=False):
+                    issues.append(
+                        f"unexpected directory in month directory: {file_entry.path}"
+                    )
+                    continue
+                date, err = _parse_note_filename(file_entry.name)
+                if err:
+                    issues.append(
+                        f"unexpected file: {file_entry.path} ({err})"
+                    )
+                    continue
+                assert date is not None
+                if date.year != year or date.month != month:
+                    issues.append(
+                        f"path mismatch: {file_entry.path}"
+                        f" (filename date {date} does not match"
+                        f" path {year}/{month:02d})"
+                    )
+                if date > today():
+                    issues.append(f"future date: {file_entry.path}")
+                if file_entry.name.endswith(ENC_EXT):
+                    seen_enc.add(date)
+                else:
+                    seen_plain.add(date)
+
+    for conflict_date in sorted(seen_plain & seen_enc):
+        issues.append(
+            f"conflicting notes for {conflict_date.isoformat()}:"
+            f" both .dn and .dn.gpg exist"
+        )
+
+    for issue in issues:
+        print(issue)
+
+    if issues:
+        print(f"\n{len(issues)} issue(s) found")
+    else:
+        print("collection is clean")
+
+    return len(issues)
+
+
+def cmd_echo(date: datetime.date) -> None:
+    target_md = (date.month, date.day)
+    matches: list[str] = []
+    for path in all_note_files():
+        parsed, err = _parse_note_filename(os.path.basename(path))
+        if err or parsed is None:
+            continue
+        if (parsed.month, parsed.day) == target_md:
+            matches.append(path)
+    matches.sort(key=lambda p: os.path.basename(p), reverse=True)
+    if not matches:
+        print(f"no notes for {date.strftime('%m-%d')} in any year")
+        return
+    for path in matches:
+        print(path)
+
+
+def cmd_near(date: datetime.date) -> None:
+    for offset in range(-3, 4):
+        candidate = date + datetime.timedelta(days=offset)
+        for confidential in (False, True):
+            path = note_path(candidate, confidential=confidential)
+            if os.path.exists(path):
+                print(path)
+
+
+def _parse_date_strict(s: str) -> datetime.date:
+    try:
+        return datetime.datetime.strptime(s, DATE_FMT).date()
+    except ValueError:
+        raise DurasInputError(
+            f"invalid date '{s}' — duras mv requires YYYY-MM-DD"
+        )
+
+
+def cmd_mv(old_date: datetime.date, new_date: datetime.date) -> None:
+    if old_date == new_date:
+        raise DurasInputError("source and destination dates are the same")
+
+    old_plain = note_path(old_date)
+    old_enc = note_path(old_date, confidential=True)
+    new_plain = note_path(new_date)
+    new_enc = note_path(new_date, confidential=True)
+
+    has_plain = os.path.exists(old_plain)
+    has_enc = os.path.exists(old_enc)
+
+    if not has_plain and not has_enc:
+        raise DurasNotFoundError(f"no note for {old_date.strftime(DATE_FMT)}")
+    if os.path.exists(new_plain) or os.path.exists(new_enc):
+        raise DurasInputError(
+            f"target date {new_date.strftime(DATE_FMT)} already has a note"
+        )
+
+    if has_plain:
+        ensure_dir(new_plain)
+    if has_enc:
+        ensure_dir(new_enc)
+
+    if has_plain:
+        os.replace(old_plain, new_plain)
+    if has_enc:
+        os.replace(old_enc, new_enc)
+
+    old_month_dir = os.path.dirname(old_plain)
+    old_year_dir = os.path.dirname(old_month_dir)
+    for dir_ in (old_month_dir, old_year_dir):
+        try:
+            os.rmdir(dir_)
+        except OSError:
+            pass

duras-1.0.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: duras
+Version: 1.0.0
+Summary: plain-text daily notes with optional encryption
+Author: Sergiy Duras
+License-Expression: ISC
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# duras
+
+[![License](https://img.shields.io/badge/license-ISC-blue)](https://opensource.org/licenses/ISC)
+
+**Daily notes as plain text files, with search and optional encryption**.
+
+---
+
+## Model
+
+One note per day:
+
+```
+
+YYYY/MM/YYYY-MM-DD.dn
+
+```
+
+Properties:
+
+- plain UTF-8 text
+- filesystem is the index
+- no database, no hidden state
+- atomic writes
+
+Encrypted note:
+
+```
+
+YYYY/MM/YYYY-MM-DD.dn.gpg
+
+````
+
+via the [GNU Privacy Guard](https://gnupg.org/).
+
+---
+
+## Scope
+
+Fits:
+
+- terminal-based workflows
+- grep-based retrieval
+- long-lived plain text notes
+- optional encryption
+
+Not a fit:
+
+- sync system
+- GUI / rich text editor
+- query engine or database
+
+---
+
+## Variants
+
+### duras
+
+- system `gpg`
+- no dependencies
+- Unix-like systems
+
+### duras_ashell
+
+- iOS [a-Shell mini](https://holzschu.github.io/a-Shell_iOS/)
+- [PGPy](https://github.com/SecurityInnovation/PGPy) (pure Python)
+- no external binaries
+- `.asc` key handling (no keyring)
+- compatible encrypted format
+
+---
+
+## Usage
+
+```sh
+duras
+duras append "note"
+duras search term
+```
+
+---
+
+## Commands
+
+### open
+
+```sh
+duras open
+duras open -1
+duras open 2026-04-19
+duras open -- +7
+```
+
+### append
+
+```sh
+duras append "text"
+duras append -d -1 "yesterday"
+cat file | duras append -
+```
+
+`-` = stdin
+
+---
+
+## Encryption
+
+```sh
+duras -c open
+duras -c append "secret"
+duras -c show
+```
+
+Notes:
+
+* uses system `gpg`
+* append is memory-only
+* editor uses temp file
+
+---
+
+## Search / tags
+
+```sh
+duras search error
+duras search todo -i
+duras tags
+```
+
+* literal match (not regex)
+* encrypted notes excluded
+
+---
+
+## Listing
+
+```sh
+duras list
+duras list -n 0
+duras stats
+```
+
+Order: filename (date), not mtime.
+
+---
+
+## Export
+
+```sh
+duras export ~/backup
+duras export ~/backup --encrypt
+```
+
+Creates archive; optional encryption avoids plaintext export.
+
+---
+
+## Dates
+
+```
+YYYY-MM-DD  absolute
+0           today
+-1          yesterday
++7          future
+```
+
+**Future dates are rejected**.
+
+---
+
+## Environment
+
+| var          | meaning                                |
+| ------------ | -------------------------------------- |
+| DURAS_DIR     | notes dir (default: ~/Documents/Notes) |
+| EDITOR       | editor fallback: nano / vi / ed        |
+| DURAS_GPG_KEY | encryption recipient                   |
+
+---
+
+## Behavior
+
+* one file per day
+* plain + encrypted may coexist
+* atomic writes
+* no index layer
+
+---
+
+## Exit codes
+
+| code | meaning          |
+| ---- | ---------------- |
+| 0    | ok               |
+| 1    | error            |
+| 2    | not found        |
+| 3    | invalid input    |
+| 4    | external failure |
+
+---
+
+## Limits
+
+* encrypted notes not searchable
+* depends on `gpg`
+
+---
+
+## Docs
+
+* **`man duras`**
+* [https://codeberg.org/duras/duras](https://codeberg.org/duras/duras)
+
+---
+
+## License
+
+ISC

duras-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+duras/__init__.py,sha256=88tpZ5w3ZPv0wFdReDNt4R-i555hcSpvt5pLaQoqabo,26
+duras/cli.py,sha256=VMlta_LDziXCW_5UlWxnh6p0mIxN5ea955PURjHvcQg,9431
+duras/core.py,sha256=GHDkS-AFtyQvf0ZkZyMVXxusB7XlxS9kRLiobxpvFL4,25136
+duras-1.0.0.dist-info/licenses/LICENSE,sha256=zBb5HTyEgCA9vWB8PQdsUnUpimhV7Sbs9qHOQt36vVE,766
+duras-1.0.0.dist-info/METADATA,sha256=3JFe7zreE-3KwaAc9bBAFbv8IQ2nNED3wmvvpjmIEdI,3042
+duras-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+duras-1.0.0.dist-info/entry_points.txt,sha256=-ex0zTSoqW-nuzWlIv_BNbkBIL5JoJppECSVE1MKrqk,41
+duras-1.0.0.dist-info/top_level.txt,sha256=ieZSfYSz-GTUFIyqzuoUJUunztvAFKGTibgRnSTD4ro,6
+duras-1.0.0.dist-info/RECORD,,

duras-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

duras-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+duras = duras.cli:main

duras-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+ISC License:
+
+Copyright (c) 2026 by Sergiy Duras https://codeberg.org/duras/duras
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted, provided that the
+above copyright notice and this permission notice appear in all
+copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY
+SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

duras-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+duras