pwdnote 0.1.0__py3-none-any.whl

pwdnote/__init__.py

@@ -0,0 +1,3 @@
+"""pwdnote — encrypted, project-local notes for your terminal."""
+
+__version__ = "0.1.0"

pwdnote/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface for pwdnote."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+from rich.console import Console
+
+from . import editor as editor_mod
+from . import notes, project
+from .config import load_or_create_key
+from .crypto import DecryptionError
+
+app = typer.Typer(
+    name="pwdnote",
+    help="Encrypted, project-local notes for your terminal.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+
+console = Console()
+
+
+def _fail(message: str) -> NoReturn:
+    console.print(message)
+    raise typer.Exit(code=1)
+
+
+def _no_note() -> NoReturn:
+    console.print("No project note found.")
+    console.print("Run:")
+    console.print("  pwdnote init")
+    raise typer.Exit(code=1)
+
+
+def _read_existing() -> tuple[Path, bytes, str]:
+    """Locate the note, load the key, and decrypt — or fail with a message."""
+    note_path = project.find_existing_note(Path.cwd())
+    if note_path is None:
+        _no_note()
+    key = load_or_create_key()
+    try:
+        text = notes.read_note(note_path, key)
+    except DecryptionError:
+        _fail("Unable to decrypt project note.")
+    except PermissionError:
+        _fail("Unable to access note file.")
+    return note_path, key, text
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Show the decrypted project note when no subcommand is given."""
+    if ctx.invoked_subcommand is not None:
+        return
+    _, _, text = _read_existing()
+    console.print(text, end="" if text.endswith("\n") else "\n", highlight=False)
+
+
+@app.command()
+def init() -> None:
+    """Create an encrypted project note."""
+    root = project.resolve_project_root(Path.cwd())
+    note_path = project.note_path_for(root)
+    key = load_or_create_key()
+    try:
+        notes.init_note(note_path, key)
+    except notes.NoteExistsError:
+        _fail("Project note already exists.")
+    except PermissionError:
+        _fail("Unable to access note file.")
+    console.print(f"Created {note_path}")
+
+
+@app.command()
+def edit() -> None:
+    """Edit the project note in your editor."""
+    note_path, key, text = _read_existing()
+    edited = editor_mod.edit_text(text, note_path.parent)
+    try:
+        notes.write_note(note_path, key, edited)
+    except PermissionError:
+        _fail("Unable to access note file.")
+    console.print("Note saved.")
+
+
+@app.command()
+def add(text: str = typer.Argument(..., help="Text to append as a bullet point.")) -> None:
+    """Append a line to the project note without opening an editor."""
+    note_path, key, _ = _read_existing()
+    try:
+        notes.append_line(note_path, key, text)
+    except PermissionError:
+        _fail("Unable to access note file.")
+    console.print(f"Added: - {text}")
+
+
+@app.command()
+def status() -> None:
+    """Show the project root, note file, and encryption status."""
+    start = Path.cwd()
+    note_path = project.find_existing_note(start)
+    if note_path is None:
+        root = project.resolve_project_root(start)
+        console.print("Project root:")
+        console.print(f"  {root}")
+        console.print("Note file:")
+        console.print("  (none — run 'pwdnote init')")
+        console.print("Encrypted:")
+        console.print("  No note yet")
+        return
+    console.print("Project root:")
+    console.print(f"  {note_path.parent}")
+    console.print("Note file:")
+    console.print(f"  {note_path.name}")
+    console.print("Encrypted:")
+    console.print("  Yes")
+
+
+@app.command()
+def gitignore() -> None:
+    """Add recommended pwdnote entries to the project's .gitignore."""
+    root = project.resolve_project_root(Path.cwd())
+    gitignore_path = root / ".gitignore"
+    recommended = [".pwdnote.tmp", ".pwdnote.cache"]
+
+    content = gitignore_path.read_text(encoding="utf-8") if gitignore_path.exists() else ""
+    existing = set(content.splitlines())
+    to_add = [entry for entry in recommended if entry not in existing]
+
+    if not to_add:
+        console.print("All recommended entries are already present.")
+        return
+
+    prefix = "" if content == "" or content.endswith("\n") else "\n"
+    with gitignore_path.open("a", encoding="utf-8") as handle:
+        handle.write(prefix + "".join(f"{entry}\n" for entry in to_add))
+
+    console.print(f"Added to {gitignore_path}:")
+    for entry in to_add:
+        console.print(f"  {entry}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

pwdnote/config.py

@@ -0,0 +1,61 @@
+"""Key management and configuration.
+
+Version 1 stores a single auto-generated key on disk with restrictive
+permissions. The lookup is structured so alternative backends (macOS Keychain,
+1Password, age, GPG) can be added later behind ``load_or_create_key``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .crypto import generate_key
+
+
+def get_config_dir() -> Path:
+    """Return the directory that holds pwdnote configuration and the key.
+
+    Honours ``PWDNOTE_CONFIG_DIR`` and ``XDG_CONFIG_HOME`` overrides, falling
+    back to ``~/.config/pwdnote``.
+    """
+    override = os.environ.get("PWDNOTE_CONFIG_DIR")
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "pwdnote"
+    return Path.home() / ".config" / "pwdnote"
+
+
+def get_key_path() -> Path:
+    """Return the path to the encryption key file."""
+    override = os.environ.get("PWDNOTE_KEY_FILE")
+    if override:
+        return Path(override)
+    return get_config_dir() / "key"
+
+
+def load_or_create_key() -> bytes:
+    """Load the encryption key, creating it on first use.
+
+    The key file is created with ``0600`` permissions inside a ``0700``
+    directory so that other users on the system cannot read it.
+    """
+    path = get_key_path()
+    if path.exists():
+        return path.read_bytes().strip()
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        # Best effort; not all filesystems support chmod.
+        pass
+
+    key = generate_key()
+    # O_EXCL guards against a concurrent writer; 0o600 keeps it private.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(key)
+    return key

pwdnote/crypto.py

@@ -0,0 +1,47 @@
+"""Crypto abstraction layer.
+
+This module isolates all cryptographic details behind a tiny interface so the
+backend can be swapped later without touching the rest of the codebase.
+
+Current backend: Fernet (AES-128-CBC + HMAC-SHA256) from the ``cryptography``
+library, which provides authenticated, integrity-protected encryption with a
+versioned token format. We intentionally do NOT implement custom cryptography.
+"""
+
+from __future__ import annotations
+
+from cryptography.fernet import Fernet, InvalidToken
+
+
+class DecryptionError(Exception):
+    """Raised when a note cannot be decrypted (wrong key or corrupted data)."""
+
+
+def generate_key() -> bytes:
+    """Generate a fresh, URL-safe base64-encoded encryption key."""
+    return Fernet.generate_key()
+
+
+def _fernet(key: bytes) -> Fernet:
+    try:
+        return Fernet(key)
+    except (ValueError, TypeError) as exc:
+        raise DecryptionError("Invalid encryption key.") from exc
+
+
+def encrypt_text(plaintext: str, key: bytes) -> bytes:
+    """Encrypt ``plaintext`` and return an opaque, integrity-protected token."""
+    return _fernet(key).encrypt(plaintext.encode("utf-8"))
+
+
+def decrypt_text(token: bytes, key: bytes) -> str:
+    """Decrypt and authenticate ``token``, returning the original text.
+
+    Raises:
+        DecryptionError: if the key is wrong, the key is malformed, or the
+            token has been tampered with / corrupted.
+    """
+    try:
+        return _fernet(key).decrypt(token).decode("utf-8")
+    except InvalidToken as exc:
+        raise DecryptionError("Unable to decrypt project note.") from exc

pwdnote/editor.py

@@ -0,0 +1,54 @@
+"""Editor integration for ``pwdnote edit``.
+
+Decrypted content is written to a temporary file with restrictive permissions,
+opened in the user's editor, and deleted afterwards so that plaintext is never
+left behind.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+_FALLBACK_EDITORS = ("nano", "vi")
+
+
+def resolve_editor() -> str:
+    """Resolve the editor command using the standard precedence.
+
+    Order: ``$VISUAL``, ``$EDITOR``, ``nano``, ``vi``.
+    """
+    for env_var in ("VISUAL", "EDITOR"):
+        value = os.environ.get(env_var)
+        if value:
+            return value
+    for candidate in _FALLBACK_EDITORS:
+        if shutil.which(candidate):
+            return candidate
+    return _FALLBACK_EDITORS[-1]
+
+
+def edit_text(initial: str, directory: Path) -> str:
+    """Open ``initial`` in an editor and return the edited result.
+
+    A temporary file is created in ``directory`` with ``0600`` permissions and
+    is always removed before returning, even if the editor fails.
+    """
+    fd, tmp_name = tempfile.mkstemp(prefix=".pwdnote", suffix=".tmp", dir=str(directory))
+    tmp_path = Path(tmp_name)
+    try:
+        os.chmod(tmp_path, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(initial)
+        editor_cmd = shlex.split(resolve_editor())
+        subprocess.run([*editor_cmd, str(tmp_path)], check=True)
+        return tmp_path.read_text(encoding="utf-8")
+    finally:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass

pwdnote/notes.py

@@ -0,0 +1,54 @@
+"""Reading and writing encrypted project notes.
+
+All persistence goes through the crypto layer, so plaintext notes are never
+written to disk.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .crypto import decrypt_text, encrypt_text
+
+INITIAL_CONTENT = "# Project Notes\n"
+
+
+class NoteNotFoundError(Exception):
+    """Raised when a note is expected but does not exist."""
+
+
+class NoteExistsError(Exception):
+    """Raised when initializing a note that already exists."""
+
+
+def note_exists(path: Path) -> bool:
+    return path.is_file()
+
+
+def read_note(path: Path, key: bytes) -> str:
+    """Decrypt and return the contents of the note at ``path``."""
+    if not path.is_file():
+        raise NoteNotFoundError(str(path))
+    return decrypt_text(path.read_bytes(), key)
+
+
+def write_note(path: Path, key: bytes, text: str) -> None:
+    """Encrypt ``text`` and write it to ``path``, overwriting any existing note."""
+    path.write_bytes(encrypt_text(text, key))
+
+
+def init_note(path: Path, key: bytes) -> None:
+    """Create a new note with the default starter content."""
+    if path.exists():
+        raise NoteExistsError(str(path))
+    write_note(path, key, INITIAL_CONTENT)
+
+
+def append_line(path: Path, key: bytes, text: str) -> str:
+    """Append ``text`` as a bullet point and return the updated note."""
+    current = read_note(path, key)
+    if current and not current.endswith("\n"):
+        current += "\n"
+    updated = f"{current}- {text}\n"
+    write_note(path, key, updated)
+    return updated

pwdnote/project.py

@@ -0,0 +1,57 @@
+"""Project root detection.
+
+Starting from the current working directory we search upward:
+
+1. If ``.pwdnote.enc`` exists, use that location.
+2. Otherwise, if ``.git`` exists, treat that location as the project root.
+3. Stop at the filesystem root.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, Optional
+
+NOTE_FILENAME = ".pwdnote.enc"
+
+
+def note_path_for(root: Path) -> Path:
+    """Return the encrypted note path for a given project root."""
+    return root / NOTE_FILENAME
+
+
+def _iter_up(start: Path) -> Iterator[Path]:
+    start = start.resolve()
+    yield start
+    yield from start.parents
+
+
+def find_existing_note(start: Path) -> Optional[Path]:
+    """Walk upward from ``start`` and return the first ``.pwdnote.enc`` found."""
+    for directory in _iter_up(start):
+        candidate = directory / NOTE_FILENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def find_git_root(start: Path) -> Optional[Path]:
+    """Walk upward from ``start`` and return the first directory with ``.git``."""
+    for directory in _iter_up(start):
+        if (directory / ".git").exists():
+            return directory
+    return None
+
+
+def resolve_project_root(start: Path) -> Path:
+    """Determine where a note should live for ``start``.
+
+    Prefers an existing note's directory, then the git root, then ``start``.
+    """
+    note = find_existing_note(start)
+    if note is not None:
+        return note.parent
+    git_root = find_git_root(start)
+    if git_root is not None:
+        return git_root
+    return start.resolve()

pwdnote-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: pwdnote
+Version: 0.1.0
+Summary: Encrypted, project-local notes for your terminal.
+Project-URL: Homepage, https://github.com/pwdnote/pwdnote
+Project-URL: Repository, https://github.com/pwdnote/pwdnote
+Project-URL: Issues, https://github.com/pwdnote/pwdnote/issues
+Author: pwdnote maintainers
+License: MIT
+License-File: LICENSE
+Keywords: cli,encryption,notes,project,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# pwdnote
+
+**Encrypted, project-local notes for your terminal.**
+
+`pwdnote` keeps project-specific notes — TODOs, deployment notes, AWS account
+details, session IDs, customer context, reminders — encrypted on disk, right
+next to your code, without ever exposing plaintext inside the repository.
+
+It is **local-first**, **encrypted-by-default**, **Git-friendly**, and
+**terminal-native**. The single encrypted file (`.pwdnote.enc`) is safe to
+commit; without your key it is just ciphertext.
+
+`pwdnote` is *not* a cloud service, a note-taking app, a password manager, a
+database, or a sync platform. It does one small thing well.
+
+---
+
+## Installation
+
+```bash
+uv tool install pwdnote
+```
+
+That's it — no further setup. The encryption key is generated automatically on
+first use.
+
+---
+
+## Quick start
+
+```bash
+cd my-project
+pwdnote init                                  # create .pwdnote.enc
+pwdnote edit                                  # open it in your editor
+pwdnote                                        # print the decrypted note
+pwdnote add "Remember to rotate AWS credentials"
+```
+
+---
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `pwdnote` | Show the decrypted project note. |
+| `pwdnote init` | Create an encrypted note (`# Project Notes`). |
+| `pwdnote edit` | Decrypt, open in `$VISUAL`/`$EDITOR`, re-encrypt on save. |
+| `pwdnote add "text"` | Append `- text` to the note without opening an editor. |
+| `pwdnote status` | Show the project root, note file, and encryption status. |
+| `pwdnote gitignore` | Add recommended ignore entries (`.pwdnote.tmp`, `.pwdnote.cache`). |
+
+### Examples
+
+```bash
+$ pwdnote
+TODO:
+- rotate AWS keys
+- update deployment docs
+Notes:
+Client requested staging environment.
+
+$ pwdnote status
+Project root:
+  ~/projects/example
+Note file:
+  .pwdnote.enc
+Encrypted:
+  Yes
+```
+
+If no note exists yet:
+
+```
+No project note found.
+Run:
+  pwdnote init
+```
+
+---
+
+## Project root detection
+
+`pwdnote` does not operate only on the current directory. Starting from your
+working directory it searches **upward**:
+
+1. If `.pwdnote.enc` exists, that location is used.
+2. Otherwise, if `.git` exists, that location is treated as the project root.
+3. The search stops at the filesystem root.
+
+So from `project/backend/api`, running `pwdnote` finds
+`project/.pwdnote.enc`.
+
+---
+
+## Security model
+
+- **Authenticated encryption.** Notes are encrypted with
+  [Fernet](https://cryptography.io/en/latest/fernet/) (AES-128-CBC with an
+  HMAC-SHA256 authentication tag) from the well-maintained `cryptography`
+  library. We do not implement custom cryptography.
+- **Integrity protection.** Tampered or corrupted files fail to decrypt rather
+  than returning garbage.
+- **Key storage.** A single key is generated on first use and stored at
+  `~/.config/pwdnote/key` (honouring `XDG_CONFIG_HOME`) with `0600`
+  permissions inside a `0700` directory.
+- **No plaintext on disk.** `pwdnote edit` writes to a temporary file with
+  restrictive permissions and always deletes it afterwards.
+- **Commit-safe.** `.pwdnote.enc` is meant to be committed; it is ciphertext.
+  Do **not** ignore it. (The temporary/cache artifacts are ignored instead.)
+
+The crypto backend lives behind a small abstraction (`encrypt_text` /
+`decrypt_text`), so it can be replaced later — and future versions may add
+macOS Keychain, 1Password, `age`, or GPG key backends.
+
+---
+
+## Limitations
+
+- The key lives on your machine. If you lose `~/.config/pwdnote/key`, encrypted
+  notes cannot be recovered. Back the key up somewhere safe.
+- There is no built-in sync. Sharing a note across machines means sharing the
+  same key (e.g. via a secrets manager).
+- One note per project root. `pwdnote` is intentionally simple — no databases,
+  no cloud, no plugins, no AI features.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/pwdnote/pwdnote
+cd pwdnote
+uv sync                 # install deps + dev tools
+uv run pytest           # run the test suite
+uv run pwdnote --help   # try the CLI from source
+```
+
+Issues and pull requests are welcome. Please keep the tool small and reliable —
+new storage/key backends should slot in behind the existing abstractions.
+
+---
+
+## License
+
+[MIT](LICENSE)

pwdnote-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pwdnote/__init__.py,sha256=cgtxqbtXmQimQNKnWnSrMus11Eqds3wOSqwV_BADngU,91
+pwdnote/cli.py,sha256=_DxinJ7ZzvIbXgPDovc2k90_rj6U8_daDsxrfnFzFlU,4446
+pwdnote/config.py,sha256=iv3K-Ai9ef4R7_ut11KtddF6X4U8BYQZnKuobh5Yh9Y,1818
+pwdnote/crypto.py,sha256=69pJ81rmgK-7kFjcdvv8VW6O1K_OHej6r7pRBdUmcxQ,1585
+pwdnote/editor.py,sha256=nhLYdJGi_nNvXOWSWgh2-lvyNCC55X8ZJUAibwCW0hU,1610
+pwdnote/notes.py,sha256=33HTAZ7043tBWdQF4Tww9sWNk-YYpxnNS-cIObOLcDw,1530
+pwdnote/project.py,sha256=-8OwmvOhtnoF0xUFi9PxF4e5_74CvgI6cPZkgViZsxU,1601
+pwdnote-0.1.0.dist-info/METADATA,sha256=dyIquFIWc-p3QIIEUoAL_IQpsY30T6GSCOtlMO2ABr8,5065
+pwdnote-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pwdnote-0.1.0.dist-info/entry_points.txt,sha256=KirbXytguyvMBrurbHmJrOLMEKmm3lmygMhFQFgRQOQ,44
+pwdnote-0.1.0.dist-info/licenses/LICENSE,sha256=SsQsQQBPBbwnM7W1YKUyvz_MhSP8NcG789uKP8jT2Hg,1070
+pwdnote-0.1.0.dist-info/RECORD,,

pwdnote-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pwdnote-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pwdnote = pwdnote.cli:app

pwdnote-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Bobrovsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.