pwdnote 0.1.0__tar.gz

pwdnote-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

pwdnote-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# pwdnote runtime artifacts (never commit decrypted/temporary notes)
+.pwdnote.tmp
+.pwdnote.cache
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store

pwdnote-0.1.0/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.

pwdnote-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,145 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "pwdnote"
+version = "0.1.0"
+description = "Encrypted, project-local notes for your terminal."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "pwdnote maintainers" }]
+keywords = ["notes", "encryption", "cli", "terminal", "project"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "cryptography>=42.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pwdnote/pwdnote"
+Repository = "https://github.com/pwdnote/pwdnote"
+Issues = "https://github.com/pwdnote/pwdnote/issues"
+
+[project.scripts]
+pwdnote = "pwdnote.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pwdnote"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+branch = true
+source = ["pwdnote"]

pwdnote-0.1.0/src/pwdnote/__init__.py

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

pwdnote-0.1.0/src/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-0.1.0/src/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