zecret 0.1.0__py3-none-any.whl

zecret/__init__.py

@@ -0,0 +1,11 @@
+"""Zecret: a modern, encrypted terminal diary."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Read from the installed distribution, so pyproject.toml stays the one
+    # place the version is written. A second copy here would eventually
+    # disagree with it, and the help screen shows this one to the user.
+    __version__ = version("zecret")
+except PackageNotFoundError:  # pragma: no cover - only when run uninstalled
+    __version__ = "0.0.0+unknown"

zecret/__main__.py

@@ -0,0 +1,41 @@
+"""CLI entry point: `zecret` launches the Textual app.
+
+Supports:
+    zecret                          # use default diary path
+    zecret --path /custom/diary.enc # override diary location
+    (or env var ZECRET_DIARY_PATH)
+
+Only the diary is configurable here. Preferences live at a fixed per-user
+path (see config.py): they are settings for the person, not for the file,
+so a diary opened with --path still uses the same theme.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from zecret.app import ZecretApp
+from zecret.storage import DEFAULT_DIARY_PATH
+
+
+def main() -> None:
+    """Parse args/env, construct ZecretApp, and run it."""
+    parser = argparse.ArgumentParser(
+        prog="zecret", description="A modern, encrypted terminal diary."
+    )
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path(os.environ.get("ZECRET_DIARY_PATH", DEFAULT_DIARY_PATH)),
+        help="Path to the encrypted diary file (default: ~/.zecret/diary.enc).",
+    )
+    args = parser.parse_args()
+
+    app = ZecretApp(diary_path=args.path)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

zecret/app.py

@@ -0,0 +1,197 @@
+"""The Zecret Textual application: screen management and app-level state.
+
+Screen flow:
+    UnlockScreen -> EntryListScreen <-> EditorScreen (one day's entry)
+                                     -> DatePromptScreen -> EditorScreen
+                                     -> SearchScreen
+                                     -> SettingsScreen (theme, password)
+                                     -> HelpScreen
+
+The unlocked DiaryFile and derived key live on the App instance for the
+duration of the session and are never persisted in plaintext. Preferences
+(the theme, and how long the diary may sit idle) are the one thing that
+outlives the session, in a separate plaintext file -- see config.py for why
+they are not in the diary.
+
+They do not live there indefinitely, though. A diary left open is a diary
+anyone at that terminal can read, so this module watches for a spell of
+quiet and puts it away again: lock() forgets both, tears the screens down
+and goes back to UnlockScreen. Everything to do with that is here rather
+than in a screen, for the same reason routing is -- it is about the session
+as a whole, not about anything on show.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from textual import events
+from textual.app import App
+
+from zecret.config import DEFAULT_CONFIG_PATH, DEFAULT_THEME, Config
+from zecret.screens.base import ZecretScreen
+from zecret.screens.entry_list import EntryListScreen
+from zecret.screens.unlock import UnlockScreen
+from zecret.storage import DEFAULT_DIARY_PATH, DiaryFile
+
+#: Said when the diary locks itself, so a screen that suddenly wants a
+#: password is not a mystery.
+LOCKED_BY_TIMEOUT = "Locked after a spell of quiet."
+LOCKED_BY_HAND = "Locked."
+
+
+class ZecretApp(App[None]):
+    """Root Textual application for Zecret."""
+
+    CSS_PATH = "app.tcss"
+    TITLE = "Zecret"
+
+    # No command palette. It offers a search over commands this app does
+    # not have, and its one useful entry -- the theme picker -- now lives
+    # on the settings screen where it can be saved. Switching it off also
+    # drops the ctrl+p binding and the footer's "^p palette" entry.
+    ENABLE_COMMAND_PALETTE = False
+
+    #: How often to ask whether the diary has been left alone long enough
+    #: to lock. Coarse on purpose: the check costs a subtraction, and
+    #: locking within half a minute of the deadline is close enough for a
+    #: timeout measured in minutes. Tests turn it right down.
+    IDLE_CHECK_SECONDS = 30.0
+
+    def __init__(
+        self,
+        diary_path: Path = DEFAULT_DIARY_PATH,
+        config_path: Path | None = None,
+    ) -> None:
+        """Store the paths; the diary itself is unlocked via UnlockScreen.
+
+        Args:
+            diary_path: Path to the encrypted diary file. Defaults to
+                ~/.zecret/diary.enc, overridable via --path / ZECRET_DIARY_PATH.
+            config_path: Path to the preferences file, defaulting to
+                DEFAULT_CONFIG_PATH. Deliberately a separate argument
+                rather than derived from diary_path: preferences belong to
+                the person, not the file, so pointing --path at a scratch
+                diary must not give it a theme of its own. Resolved here
+                rather than as a default value so the fallback can be
+                redirected in tests, which must never read or write the
+                real one.
+        """
+        super().__init__()
+        self.diary_path = diary_path
+        self.config = Config.load(DEFAULT_CONFIG_PATH if config_path is None else config_path)
+        # Both are None until UnlockScreen succeeds, and live only in memory
+        # for the session. Screens reach the diary exclusively through these.
+        self.diary: DiaryFile | None = None
+        self.key: bytes | None = None
+        # When something last happened. Monotonic, so the diary does not
+        # stay open an hour longer because a clock went backwards.
+        self.last_activity = time.monotonic()
+
+    def on_mount(self) -> None:
+        """Apply the saved theme, then push UnlockScreen, which prompts to
+        unlock or to create a diary depending on whether diary_path exists.
+
+        Routing lives here rather than in the screens: UnlockScreen reports
+        success by dismissing, and this decides what comes next.
+        """
+        self.apply_theme(self.config.theme)
+        creating = not self.diary_path.exists()
+        self.push_screen(UnlockScreen(creating=creating), self._on_unlocked)
+        self.set_interval(self.IDLE_CHECK_SECONDS, self.lock_if_idle)
+
+    async def on_event(self, event: events.Event) -> None:
+        """Every event the app sees, which is where activity is noticed.
+
+        Key events reach here even when a widget goes on to consume them --
+        typing into the editor's TextArea counts, and has to, or writing a
+        long entry would be the one thing that looks like being away.
+        """
+        if isinstance(event, events.Key | events.MouseDown):
+            self.last_activity = time.monotonic()
+        await super().on_event(event)
+
+    def apply_theme(self, theme: str) -> None:
+        """Switch to `theme`, or to the default if it is not a real theme.
+
+        Config holds whatever string was in the file, which may name a
+        theme this Textual no longer ships; setting it directly would raise
+        and take the app down over a preference.
+        """
+        self.theme = theme if theme in self.available_themes else DEFAULT_THEME
+
+    def _on_unlocked(self, _result: None) -> None:
+        """Called once UnlockScreen dismisses, i.e. the diary is open."""
+        self.push_screen(EntryListScreen())
+
+    def lock_if_idle(self) -> None:
+        """Lock the diary if it has been left alone long enough.
+
+        Runs on a timer whether or not anything is unlocked, since the
+        setting can be changed mid-session and the lock screen itself has
+        nothing to lock.
+
+        Not named check_idle: Textual's MessagePump already has one, it
+        means "the message queue has drained" rather than "nobody is
+        there", and it is called from refresh() -- so taking that name
+        replaces a framework method with one that wants attributes the app
+        has not set yet, and every test dies in App.__init__.
+        """
+        minutes = self.config.lock_after_minutes
+        if minutes <= 0 or not self.is_unlocked:
+            return
+        if self.locking_would_lose_work():
+            # Half-written entry on the screen. Treat waiting on the writer
+            # as activity rather than merely postponing: locking the moment
+            # they saved would be the same ambush a beat later.
+            self.last_activity = time.monotonic()
+            return
+        if time.monotonic() - self.last_activity >= minutes * 60:
+            self.lock(LOCKED_BY_TIMEOUT)
+
+    def locking_would_lose_work(self) -> bool:
+        """Whether any screen on the stack is holding something unsaved.
+
+        The whole stack, not just the top one: a confirmation modal over a
+        half-written entry is still a half-written entry.
+        """
+        return any(
+            isinstance(screen, ZecretScreen) and screen.blocks_lock for screen in self.screen_stack
+        )
+
+    def lock(self, message: str = LOCKED_BY_HAND) -> None:
+        """Forget the diary and the key, and go back to the lock screen.
+
+        Everything above the lock screen is torn down first, while the
+        diary is still open: screens rebuild themselves as they resume, and
+        one resuming into a locked app has nothing to draw from.
+        """
+        if not self.is_unlocked:
+            return
+        while len(self.screen_stack) > 1:
+            self.pop_screen()
+        self.diary = None
+        self.key = None
+        self.push_screen(UnlockScreen(creating=False), self._on_unlocked)
+        self.notify(message)
+
+    @property
+    def is_unlocked(self) -> bool:
+        """Whether there is an open diary to be working in."""
+        return self.diary is not None and self.key is not None
+
+    @property
+    def unlocked(self) -> tuple[DiaryFile, bytes]:
+        """The open diary and the key it was opened with.
+
+        Every screen after UnlockScreen needs both, and needs them non-None.
+        Reaching here before unlocking is a routing bug, not a user error,
+        so it raises rather than returning a half-open state.
+
+        Raises:
+            RuntimeError: if the diary has not been unlocked yet.
+        """
+        if self.diary is None or self.key is None:
+            raise RuntimeError("the diary is not unlocked")
+        return self.diary, self.key

zecret/app.tcss

@@ -0,0 +1,288 @@
+/* Zecret Textual stylesheet.
+
+   Conventions, so the screens stay consistent as they grow:
+
+   - Colors come from Textual's theme variables ($surface, $accent, $error,
+     $text-muted, ...), never hard-coded. The app then follows whichever
+     theme the user picks, light or dark, with no second palette to keep in
+     sync.
+   - $accent frames anything you are working in; $error is reserved for
+     errors and destructive actions and is used nowhere else.
+   - Spacing is 1 cell vertically, 2 horizontally. Terminal cells are about
+     twice as tall as they are wide, so that pair reads as even.
+   - Rules are grouped by the role a widget plays (panel, title, hint,
+     error, list), not by the screen it happens to live on -- which is why
+     selectors here list several ids at once.
+*/
+
+/* --- Title bar ---------------------------------------------------------- */
+
+/* Zecret's own header, not Textual's: one line, no icon, nothing to click.
+   $panel keeps it distinct from the screen behind it without competing with
+   $accent, which is reserved for what you are working in. */
+DiaryHeader {
+    dock: top;
+    width: 100%;
+    height: 1;
+    background: $panel;
+    color: $foreground;
+    content-align: center middle;
+    text-wrap: nowrap;
+    text-overflow: ellipsis;
+}
+
+/* --- Panels: the centred card used by unlock and settings --------------- */
+
+UnlockScreen,
+SettingsScreen {
+    align: center middle;
+}
+
+#unlock-box,
+#settings-box {
+    width: 62;
+    height: auto;
+    /* Never taller than the terminal: settings scrolls inside its border
+       rather than running off the bottom of a short window. */
+    max-height: 100%;
+    padding: 1 2;
+    border: round $accent;
+    background: $surface;
+}
+
+#unlock-title,
+.section-title {
+    width: 100%;
+    content-align: center middle;
+    text-style: bold;
+    color: $text-accent;
+    padding-bottom: 1;
+}
+
+#unlock-hint,
+.section-hint {
+    width: 100%;
+    color: $text-muted;
+    padding-bottom: 1;
+}
+
+#unlock-box Input,
+#settings-box Input,
+/* The gap under the theme picker is what separates the two sections of
+   the settings screen; they need no rule of their own. */
+#settings-box Select {
+    margin-bottom: 1;
+}
+
+/* --- Error lines -------------------------------------------------------- */
+
+/* Reserve the row whether or not there is a message, so showing one never
+   shifts the fields under the user's cursor. */
+#unlock-error,
+#settings-error,
+#editor-error,
+#date-error {
+    width: 100%;
+    height: 1;
+    color: $text-error;
+}
+
+/* --- Lists: entry list and search results ------------------------------- */
+
+#entries,
+#results {
+    height: 1fr;
+    /* Same 2-cell gutter as the search box above it and the editor's
+       fields, so text lines up down the left edge of every screen. */
+    margin: 0 2;
+    background: $surface;
+    border: none;
+
+    & > ListItem {
+        padding: 0 2;
+        background: transparent;
+    }
+
+    /* The selected row is the one thing the eye should find instantly. */
+    & > ListItem.-highlight {
+        background: $accent-muted;
+        text-style: bold;
+    }
+
+    &:focus > ListItem.-highlight {
+        background: $accent;
+        color: $block-cursor-foreground;
+    }
+
+    /* Month headings. Disabled so the cursor skips them, which is a
+       navigation decision, not a visual one -- they read as headings, not
+       as something unavailable. */
+    & > ListItem.group-heading {
+        padding: 1 2 0 2;
+        color: $text-accent;
+        text-style: bold;
+    }
+}
+
+/* --- Empty states ------------------------------------------------------- */
+
+#entries-empty,
+#search-empty {
+    height: 1fr;
+    width: 100%;
+    content-align: center middle;
+    color: $text-muted;
+}
+
+/* --- SearchScreen ------------------------------------------------------- */
+
+#query {
+    margin: 0 2;
+    border: round $border-blurred;
+
+    &:focus {
+        border: round $accent;
+    }
+}
+
+/* --- EditorScreen ------------------------------------------------------- */
+
+#editor-box {
+    height: 1fr;
+    padding: 1 2;
+}
+
+#editor-box #body {
+    height: 1fr;
+    margin-bottom: 1;
+    border: round $border-blurred;
+
+    &:focus {
+        border: round $accent;
+    }
+}
+
+/* --- HelpScreen (modal) ------------------------------------------------- */
+
+/* Wide enough for the logo, and never taller than the terminal: the help
+   scrolls inside its own border rather than off the bottom of the screen. */
+#help-box {
+    width: 62;
+    max-width: 100%;
+    height: auto;
+    max-height: 100%;
+    padding: 1 2;
+    border: round $accent;
+    background: $surface;
+}
+
+#help-logo {
+    width: auto;
+    color: $text-accent;
+    /* The art is drawn, not written: wrapping it would make nonsense of
+       it. Narrow terminals hide it instead -- see HelpScreen.fit_logo. */
+    text-wrap: nowrap;
+}
+
+#help-tagline {
+    width: 100%;
+    color: $text-muted;
+    padding-bottom: 1;
+}
+
+/* Section titles are centred where they head a narrow card; here they head
+   a list, so they read as headings only if they sit at the left edge of
+   what they introduce, with air above rather than below. */
+#help-box .section-title {
+    content-align: left middle;
+    text-align: left;
+    padding: 1 0 0 0;
+}
+
+/* The key rows are aligned into columns by the screen itself, since only
+   it knows how wide the widest key in a section is. */
+.help-key {
+    width: 100%;
+}
+
+/* A tight list, like the key rows above: each note is one line, and the
+   section heading already gives the group its air. */
+.help-note {
+    width: 100%;
+    color: $text-muted;
+}
+
+/* No padding above it: this is the one line someone who feels stuck needs
+   to see, so it earns its place inside the fold rather than a row of air. */
+#help-close-hint {
+    width: 100%;
+    content-align: right middle;
+    text-align: right;
+    color: $text-muted;
+}
+
+/* --- Modals: confirm, date prompt and help ------------------------------ */
+
+/* Dim what is behind them: the question is the only thing to answer, and
+   help sits over the diary rather than replacing it. */
+ConfirmScreen,
+DatePromptScreen,
+HelpScreen {
+    align: center middle;
+    background: $background 60%;
+}
+
+#confirm-box {
+    width: 60;
+    height: auto;
+    padding: 1 2;
+    /* Red framing, because every use of this modal is destructive. */
+    border: round $error;
+    background: $surface;
+}
+
+#confirm-question {
+    width: 100%;
+    padding-bottom: 1;
+}
+
+#confirm-buttons {
+    height: auto;
+    align-horizontal: right;
+}
+
+#confirm-buttons Button {
+    margin-left: 2;
+}
+
+/* --- DatePromptScreen (modal) ------------------------------------------- */
+
+/* $accent, not $error: picking a day is where you start writing, not a
+   destructive step. */
+#date-box {
+    width: 44;
+    height: auto;
+    padding: 1 2;
+    border: round $accent;
+    background: $surface;
+}
+
+#date-title {
+    width: 100%;
+    text-style: bold;
+    color: $text-accent;
+    padding-bottom: 1;
+}
+
+#date-hint {
+    width: 100%;
+    color: $text-muted;
+}
+
+#date-box MaskedInput {
+    border: round $border-blurred;
+
+    &:focus {
+        border: round $accent;
+    }
+}

zecret/config.py

@@ -0,0 +1,112 @@
+"""User preferences: small, non-secret, and kept out of the diary.
+
+The diary file is for what you wrote. A theme is neither secret nor
+writing, and it has to be known *before* the diary is unlocked -- the lock
+screen is themed too -- so it cannot live inside a file that needs a
+password to read. The same goes for how long the diary waits before
+locking itself: the timer has to be running before anything is unlocked.
+Both get their own plaintext JSON file instead:
+
+    {"theme": "gruvbox", "lock_after_minutes": 15}
+
+This is the one place besides storage.py that touches the filesystem, and
+the one file Zecret writes in the clear. It may hold preferences and
+nothing else: no entry text, no dates, no password, nothing derived from
+the key. Anything that would tell a reader of this file something about
+the diary's contents belongs in the diary.
+
+Preferences are regenerable, so this module is forgiving where storage.py
+is strict. A missing, unreadable, or malformed config falls back to
+defaults rather than raising: a mangled preference must never be the
+reason you cannot get to your diary. For the same reason the write is a
+plain write rather than the atomic dance storage.py performs -- the worst
+outcome is a file that fails to parse next launch and is replaced by
+defaults.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Self
+
+DEFAULT_CONFIG_PATH = Path.home() / ".zecret" / "config.json"
+
+#: What the app uses until told otherwise, and the fallback for anything
+#: unreadable. Matches Textual's own default theme.
+DEFAULT_THEME = "textual-dark"
+
+#: Minutes of no typing before the diary locks itself. Long enough not to
+#: interrupt someone thinking about what to write, short enough that a
+#: walked-away-from terminal does not stay open all afternoon. Zero turns
+#: it off, which is a choice the settings screen offers rather than the
+#: default it ships.
+DEFAULT_LOCK_AFTER_MINUTES = 15
+
+DIR_MODE = 0o700
+
+
+@dataclass(slots=True)
+class Config:
+    """The user's preferences, and where they came from.
+
+    Attributes:
+        path: The file these were read from, and where save() writes back.
+        theme: Name of the Textual theme to use. Not validated here --
+            config.py has no opinion on which themes exist; the app checks
+            the name against the themes actually registered and falls back
+            if it does not know it.
+        lock_after_minutes: Minutes of inactivity before the diary locks
+            itself, or 0 to never lock. How long a minute is and what
+            counts as inactivity are the app's business; this only
+            remembers the number, and only a whole non-negative one.
+    """
+
+    path: Path
+    theme: str = DEFAULT_THEME
+    lock_after_minutes: int = DEFAULT_LOCK_AFTER_MINUTES
+
+    @classmethod
+    def load(cls, path: Path) -> Self:
+        """Read preferences from `path`, falling back to defaults.
+
+        Never raises: a missing file is the normal first-run case, and a
+        corrupt or unreadable one is treated the same way, since the diary
+        must stay reachable regardless.
+        """
+        config = cls(path=path)
+        try:
+            document = json.loads(path.read_bytes().decode("utf-8"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+            return config
+        if not isinstance(document, dict):
+            return config
+
+        theme = document.get("theme")
+        if isinstance(theme, str) and theme:
+            config.theme = theme
+
+        lock_after = document.get("lock_after_minutes")
+        # bool is an int in Python, and `true` in the file is not a number
+        # of minutes. A negative one would lock the diary the instant it
+        # opened, so it falls back rather than being clamped -- the file is
+        # not saying anything we can act on.
+        if isinstance(lock_after, int) and not isinstance(lock_after, bool) and lock_after >= 0:
+            config.lock_after_minutes = lock_after
+        return config
+
+    def save(self) -> None:
+        """Write preferences back to self.path, creating the directory.
+
+        Raises:
+            OSError: if the file cannot be written. The caller decides what
+                to say about it -- the setting still applies to this
+                session, it just will not outlive it.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=DIR_MODE)
+        self.path.write_text(json.dumps(self.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+    def to_dict(self) -> dict[str, Any]:
+        """The JSON shape written to disk."""
+        return {"theme": self.theme, "lock_after_minutes": self.lock_after_minutes}