hyprmuse 0.3.2__tar.gz

hyprmuse-0.3.2/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+# leftover scraped output; the library lives in ~/.local/share/hyprmuse/
+lyrics.json
+
+# The tracker's specs, tickets and review records (docs/agents/issue-tracker.md)
+.scratch/
+
+# What scripts/gate writes
+.coverage
+coverage.xml
+test-results.xml
+quality.md
+
+# What packaging/build-binary.sh writes
+build/
+dist/

hyprmuse-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Siegl
+
+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.

hyprmuse-0.3.2/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: hyprmuse
+Version: 0.3.2
+Summary: Random quotes from musicians, authors and poets for hyprlock
+Project-URL: Homepage, https://github.com/DavidSiegl/hyprmuse
+Project-URL: Issues, https://github.com/DavidSiegl/hyprmuse/issues
+Project-URL: Releases, https://github.com/DavidSiegl/hyprmuse/releases
+Author: David Siegl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: hyprland,hyprlock,lockscreen,quotes
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.14
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/DavidSiegl/hyprmuse/main/assets/logo.svg" width="84" height="84" alt="">
+  <br>
+  hyprmuse
+</h1>
+
+<p align="center">
+  Random quotes from musicians, literary authors, poets and public-domain books,
+  for your <code>hyprlock</code> screen.
+</p>
+
+Name a subject, hyprmuse harvests them from a fitting source into a local
+library, and prints a random quote on demand. Everything is stored offline, so
+the lockscreen never waits on the network.
+
+## Sources
+
+| Source | Domain | Covers | Licence |
+|---|---|---|---|
+| `wikiquote` | quotations | authors, philosophers, scientists, films, TV, proverbs — any language edition | CC BY-SA |
+| `genius` | music | song lyrics for any artist | scraped, personal use |
+| `poetrydb` | poetry | ~130 classic poets, full poems | public domain |
+| `gutenberg` | prose | passages from public-domain books | public domain |
+
+Sources fall into two kinds. **Sliceable** items (lyrics, poems) are quoted as a
+random window of consecutive lines taken from within one stanza, so a slice
+never runs from a verse into its chorus. **Atomic** items (a Wikiquote
+quotation, a prose passage) are quoted whole and word-wrapped.
+
+Every pick is checked against the box it has to fit (`width`, `max_lines`,
+`max_chars`). A window that overflows is shortened a line at a time, and an
+item that cannot fit at all is skipped in favour of another. Only when nothing
+in the library fits does the output get cut off.
+
+Libraries harvested before stanza breaks were stored still work, but slice as
+one long stanza. Run `hyprmuse update --all` once to pick the breaks up.
+
+## Setup
+
+Download the Linux binary from the [latest release](https://github.com/DavidSiegl/hyprmuse/releases/latest),
+which needs no Python, and check it:
+
+```bash
+curl -LO https://github.com/DavidSiegl/hyprmuse/releases/latest/download/hyprmuse-linux-x86_64
+curl -LO https://github.com/DavidSiegl/hyprmuse/releases/latest/download/hyprmuse-linux-x86_64.sha256
+sha256sum -c hyprmuse-linux-x86_64.sha256
+install -D -m 755 hyprmuse-linux-x86_64 ~/.local/bin/hyprmuse
+```
+
+Or run it from a checkout with `uv sync`, then `uv run hyprmuse` in place of `hyprmuse`
+below.
+
+## Usage
+
+```bash
+# add subjects — omit --source to search every source and pick from a list
+hyprmuse add "Element of Crime" --source genius
+hyprmuse add "Ingeborg Bachmann" --source wikiquote --lang de
+hyprmuse add "Emily Dickinson" --source poetrydb
+hyprmuse add "Frankenstein" --source gutenberg
+
+hyprmuse search "Nietzsche" --lang de   # look without harvesting
+hyprmuse list                           # what's stored
+hyprmuse update --all                   # re-harvest everything
+hyprmuse remove "genius:342499"
+
+hyprmuse quote                          # a random quote
+hyprmuse quote --domain poetry --width 50
+hyprmuse quote --max-lines 4 --max-chars 160  # fit a small label
+hyprmuse quote --source wikiquote --note
+hyprmuse quote --seed 42                # deterministic
+```
+
+`--lang` selects the Wikiquote language edition (`de`, `en`, `fr`, …). Harvesting
+is throttled and cached; `add` is the slow step, `quote` reads only local files.
+
+## Hyprlock integration
+
+```ini
+label {
+    monitor =
+    text = cmd[update:0] ~/.local/bin/hyprmuse quote --width 60
+    color = rgba(200, 200, 200, 1.0)
+    font_size = 20
+    font_family = Noto Sans
+    position = 0, 80
+    halign = center
+    valign = center
+}
+```
+
+From a checkout, the command is `/path/to/hyprmuse/.venv/bin/hyprmuse`.
+`quote.py` is kept as a compatibility shim, so an existing config pointing at
+`/path/to/hyprmuse/quote.py` keeps working — only the directory name changed.
+
+## Configuration
+
+Optional, at `~/.config/hyprmuse/config.toml`:
+
+```toml
+[quote]
+lines = 3           # lines taken from sliceable items
+width = 60          # wrap width, 0 disables wrapping
+max_lines = 6       # most lines after wrapping, 0 disables
+max_chars = 0       # most characters after wrapping, 0 disables
+min_line_chars = 2  # skip lines shorter than this ("-", "I") when slicing
+weighting = "subject"  # "subject" = every subject equally likely
+                       # "quote"   = every quote equally likely
+avoid_repeats = 20  # don't repeat within the last N quotes
+
+# per-subject overrides, keyed as shown by `hyprmuse list`
+[subjects."genius:342499"]
+weight = 2.0
+enabled = true
+```
+
+`weighting = "subject"` is the default so a 162-song band does not drown out an
+author with nine quotes.
+
+## Storage
+
+```
+~/.local/share/hyprmuse/subjects/*.json   one file per subject
+~/.local/share/hyprmuse/recent.json       recently shown, for repeat avoidance
+~/.config/hyprmuse/config.toml            optional settings
+```
+
+Harvested text lives outside the repository, so scraped content stays out of git.
+
+## Development
+
+```bash
+uv run pytest               # the tests
+scripts/gate origin/main    # the tests with coverage, then octoflow-ai's quality gate on
+                            # the change since origin/main, as Jenkins runs it; writes quality.md
+```
+
+Opening a pull request hands it over: once Jenkins passes it, one that changes only the
+package's or the tests' Python, or Markdown, merges into `main` without a human.
+`docs/agents/README.md` has the exact rule and how to hold a pull request back.
+
+A merge into `main` that raises `version` in `pyproject.toml` releases it: Jenkins builds
+the binary with `packaging/build-binary.sh` and publishes it as release `v<version>`.
+The Jenkins job `hyprmuse-pypi` (`packaging/pypi/Jenkinsfile`) then builds that release's
+tag on a trusted node and uploads the sdist and wheel to PyPI, and `hyprmuse-aur`
+(`packaging/aur/Jenkinsfile`) pushes the AUR's `hyprmuse-bin` to that release with
+`packaging/aur/publish.sh`. To change the AUR package itself between releases, edit
+`packaging/aur/PKGBUILD`, run `packaging/aur/update.sh` with the latest released version,
+raise `pkgrel`, and run `update.sh` again to refresh `.SRCINFO`. Once merged, the change
+reaches the AUR on the job's next run, after the next build of `main` or within a day.
+
+## License
+
+MIT; see `LICENSE`. The release binary also bundles Python, the packages hyprmuse
+depends on, and the C libraries linked into them, each under its own license; each
+release carries their notices as `hyprmuse-third-party-licenses.txt`.

hyprmuse-0.3.2/README.md

@@ -0,0 +1,156 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/DavidSiegl/hyprmuse/main/assets/logo.svg" width="84" height="84" alt="">
+  <br>
+  hyprmuse
+</h1>
+
+<p align="center">
+  Random quotes from musicians, literary authors, poets and public-domain books,
+  for your <code>hyprlock</code> screen.
+</p>
+
+Name a subject, hyprmuse harvests them from a fitting source into a local
+library, and prints a random quote on demand. Everything is stored offline, so
+the lockscreen never waits on the network.
+
+## Sources
+
+| Source | Domain | Covers | Licence |
+|---|---|---|---|
+| `wikiquote` | quotations | authors, philosophers, scientists, films, TV, proverbs — any language edition | CC BY-SA |
+| `genius` | music | song lyrics for any artist | scraped, personal use |
+| `poetrydb` | poetry | ~130 classic poets, full poems | public domain |
+| `gutenberg` | prose | passages from public-domain books | public domain |
+
+Sources fall into two kinds. **Sliceable** items (lyrics, poems) are quoted as a
+random window of consecutive lines taken from within one stanza, so a slice
+never runs from a verse into its chorus. **Atomic** items (a Wikiquote
+quotation, a prose passage) are quoted whole and word-wrapped.
+
+Every pick is checked against the box it has to fit (`width`, `max_lines`,
+`max_chars`). A window that overflows is shortened a line at a time, and an
+item that cannot fit at all is skipped in favour of another. Only when nothing
+in the library fits does the output get cut off.
+
+Libraries harvested before stanza breaks were stored still work, but slice as
+one long stanza. Run `hyprmuse update --all` once to pick the breaks up.
+
+## Setup
+
+Download the Linux binary from the [latest release](https://github.com/DavidSiegl/hyprmuse/releases/latest),
+which needs no Python, and check it:
+
+```bash
+curl -LO https://github.com/DavidSiegl/hyprmuse/releases/latest/download/hyprmuse-linux-x86_64
+curl -LO https://github.com/DavidSiegl/hyprmuse/releases/latest/download/hyprmuse-linux-x86_64.sha256
+sha256sum -c hyprmuse-linux-x86_64.sha256
+install -D -m 755 hyprmuse-linux-x86_64 ~/.local/bin/hyprmuse
+```
+
+Or run it from a checkout with `uv sync`, then `uv run hyprmuse` in place of `hyprmuse`
+below.
+
+## Usage
+
+```bash
+# add subjects — omit --source to search every source and pick from a list
+hyprmuse add "Element of Crime" --source genius
+hyprmuse add "Ingeborg Bachmann" --source wikiquote --lang de
+hyprmuse add "Emily Dickinson" --source poetrydb
+hyprmuse add "Frankenstein" --source gutenberg
+
+hyprmuse search "Nietzsche" --lang de   # look without harvesting
+hyprmuse list                           # what's stored
+hyprmuse update --all                   # re-harvest everything
+hyprmuse remove "genius:342499"
+
+hyprmuse quote                          # a random quote
+hyprmuse quote --domain poetry --width 50
+hyprmuse quote --max-lines 4 --max-chars 160  # fit a small label
+hyprmuse quote --source wikiquote --note
+hyprmuse quote --seed 42                # deterministic
+```
+
+`--lang` selects the Wikiquote language edition (`de`, `en`, `fr`, …). Harvesting
+is throttled and cached; `add` is the slow step, `quote` reads only local files.
+
+## Hyprlock integration
+
+```ini
+label {
+    monitor =
+    text = cmd[update:0] ~/.local/bin/hyprmuse quote --width 60
+    color = rgba(200, 200, 200, 1.0)
+    font_size = 20
+    font_family = Noto Sans
+    position = 0, 80
+    halign = center
+    valign = center
+}
+```
+
+From a checkout, the command is `/path/to/hyprmuse/.venv/bin/hyprmuse`.
+`quote.py` is kept as a compatibility shim, so an existing config pointing at
+`/path/to/hyprmuse/quote.py` keeps working — only the directory name changed.
+
+## Configuration
+
+Optional, at `~/.config/hyprmuse/config.toml`:
+
+```toml
+[quote]
+lines = 3           # lines taken from sliceable items
+width = 60          # wrap width, 0 disables wrapping
+max_lines = 6       # most lines after wrapping, 0 disables
+max_chars = 0       # most characters after wrapping, 0 disables
+min_line_chars = 2  # skip lines shorter than this ("-", "I") when slicing
+weighting = "subject"  # "subject" = every subject equally likely
+                       # "quote"   = every quote equally likely
+avoid_repeats = 20  # don't repeat within the last N quotes
+
+# per-subject overrides, keyed as shown by `hyprmuse list`
+[subjects."genius:342499"]
+weight = 2.0
+enabled = true
+```
+
+`weighting = "subject"` is the default so a 162-song band does not drown out an
+author with nine quotes.
+
+## Storage
+
+```
+~/.local/share/hyprmuse/subjects/*.json   one file per subject
+~/.local/share/hyprmuse/recent.json       recently shown, for repeat avoidance
+~/.config/hyprmuse/config.toml            optional settings
+```
+
+Harvested text lives outside the repository, so scraped content stays out of git.
+
+## Development
+
+```bash
+uv run pytest               # the tests
+scripts/gate origin/main    # the tests with coverage, then octoflow-ai's quality gate on
+                            # the change since origin/main, as Jenkins runs it; writes quality.md
+```
+
+Opening a pull request hands it over: once Jenkins passes it, one that changes only the
+package's or the tests' Python, or Markdown, merges into `main` without a human.
+`docs/agents/README.md` has the exact rule and how to hold a pull request back.
+
+A merge into `main` that raises `version` in `pyproject.toml` releases it: Jenkins builds
+the binary with `packaging/build-binary.sh` and publishes it as release `v<version>`.
+The Jenkins job `hyprmuse-pypi` (`packaging/pypi/Jenkinsfile`) then builds that release's
+tag on a trusted node and uploads the sdist and wheel to PyPI, and `hyprmuse-aur`
+(`packaging/aur/Jenkinsfile`) pushes the AUR's `hyprmuse-bin` to that release with
+`packaging/aur/publish.sh`. To change the AUR package itself between releases, edit
+`packaging/aur/PKGBUILD`, run `packaging/aur/update.sh` with the latest released version,
+raise `pkgrel`, and run `update.sh` again to refresh `.SRCINFO`. Once merged, the change
+reaches the AUR on the job's next run, after the next build of `main` or within a day.
+
+## License
+
+MIT; see `LICENSE`. The release binary also bundles Python, the packages hyprmuse
+depends on, and the C libraries linked into them, each under its own license; each
+release carries their notices as `hyprmuse-third-party-licenses.txt`.

hyprmuse-0.3.2/hyprmuse/__init__.py

@@ -0,0 +1 @@
+"""hyprmuse - random quotes from musicians, authors and poets for hyprlock."""

hyprmuse-0.3.2/hyprmuse/__main__.py

@@ -0,0 +1,10 @@
+"""Run the hyprmuse command: `python -m hyprmuse`, and the release binary's entry point.
+
+The import is absolute because packaging/build-binary.sh hands this file to PyInstaller
+as a plain script, outside the package, where a relative import has no parent.
+"""
+
+from hyprmuse.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyprmuse-0.3.2/hyprmuse/cli.py

@@ -0,0 +1,232 @@
+"""Command line interface for hyprmuse."""
+
+import argparse
+import sys
+
+from . import config, library, lockscreen
+from .sources import AUTO_ORDER, REGISTRY, SourceError, get_source
+from .sources.base import Candidate
+
+
+def _err(msg: str) -> int:
+    print(f"hyprmuse: {msg}", file=sys.stderr)
+    return 1
+
+
+def _progress(msg: str) -> None:
+    print(f"  {msg}", file=sys.stderr)
+
+
+def _gather(query: str, source: str, lang: str) -> list[Candidate]:
+    """Candidates from one named source, or from every source in auto order."""
+    names = [source] if source else AUTO_ORDER
+    found: list[Candidate] = []
+    for name in names:
+        try:
+            hits = get_source(name).search(query, lang)
+        except SourceError as exc:
+            if source:
+                raise
+            print(f"  ({name} unavailable: {exc})", file=sys.stderr)
+            continue
+        found.extend(hits)
+        if source:
+            break
+    return found
+
+
+def _choose(cands: list[Candidate], assume_yes: bool) -> Candidate | None:
+    if not cands:
+        return None
+    if assume_yes or len(cands) == 1 or not sys.stdin.isatty():
+        return cands[0]
+    print("\nMatches:", file=sys.stderr)
+    for i, c in enumerate(cands, 1):
+        hint = f"  ({c.hint})" if c.hint else ""
+        print(f"  {i:2}. [{c.source}/{c.domain}] {c.name}{hint}", file=sys.stderr)
+    try:
+        raw = input("\nPick a number (blank to cancel): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        return None
+    if not raw.isdigit() or not 1 <= int(raw) <= len(cands):
+        return None
+    return cands[int(raw) - 1]
+
+
+def cmd_search(args) -> int:
+    cands = _gather(args.query, args.source, args.lang)
+    if not cands:
+        return _err(f"no matches for {args.query!r}")
+    for c in cands:
+        hint = f"  ({c.hint})" if c.hint else ""
+        print(f"[{c.source}/{c.domain}] {c.name}{hint}\n    {c.source}:{c.source_id}")
+    return 0
+
+
+def cmd_add(args) -> int:
+    try:
+        cands = _gather(args.query, args.source, args.lang)
+    except SourceError as exc:
+        return _err(str(exc))
+    cand = _choose(cands, args.yes)
+    if cand is None:
+        return _err(f"no match chosen for {args.query!r}")
+    print(f"Harvesting {cand.name} from {cand.source}…", file=sys.stderr)
+    try:
+        subject = get_source(cand.source).fetch(cand.source_id, _progress)
+    except SourceError as exc:
+        return _err(str(exc))
+    path = library.save(subject)
+    print(f"Saved {len(subject.items)} items for {subject.name} -> {path}")
+    return 0
+
+
+def cmd_list(args) -> int:
+    subjects = library.load_all()
+    if not subjects:
+        print("No subjects yet. Try: hyprmuse add \"Franz Kafka\"")
+        return 0
+    width = max(len(s.name) for s in subjects)
+    total = 0
+    for s in subjects:
+        total += len(s.items)
+        kind = "atomic" if s.items and s.items[0].atomic else "sliceable"
+        print(f"{s.name:{width}}  {len(s.items):5} items  {s.domain:11} "
+              f"{s.lang:3} {kind:10} {library.subject_key(s.source, s.source_id)}")
+    print(f"\n{len(subjects)} subjects, {total} items total")
+    return 0
+
+
+def cmd_remove(args) -> int:
+    matches = library.find(args.token)
+    if not matches:
+        return _err(f"no subject matching {args.token!r}")
+    if len(matches) > 1:
+        names = ", ".join(library.subject_key(m.source, m.source_id) for m in matches)
+        return _err(f"{args.token!r} is ambiguous: {names}")
+    subject = matches[0]
+    library.remove(subject)
+    print(f"Removed {subject.name}")
+    return 0
+
+
+def cmd_update(args) -> int:
+    targets = library.load_all() if args.all else library.find(args.token or "")
+    if not targets:
+        return _err("nothing to update")
+    failed = 0
+    for subj in targets:
+        print(f"Updating {subj.name} ({subj.source})…", file=sys.stderr)
+        try:
+            fresh = get_source(subj.source).fetch(subj.source_id, _progress)
+        except SourceError as exc:
+            print(f"  failed: {exc}", file=sys.stderr)
+            failed += 1
+            continue
+        library.save(fresh)
+        print(f"  {len(fresh.items)} items")
+    return 1 if failed and failed == len(targets) else 0
+
+
+def cmd_sources(args) -> int:
+    for name in AUTO_ORDER:
+        src = REGISTRY[name]
+        kind = "atomic" if src.produces_atomic else "sliceable"
+        print(f"{name:11} {src.domain:11} {kind}")
+    return 0
+
+
+def cmd_quote(args) -> int:
+    cfg = config.load_config()
+    for key, flag in (("lines", args.lines), ("width", args.width),
+                      ("max_lines", args.max_lines), ("max_chars", args.max_chars)):
+        if flag is not None:
+            cfg[key] = flag
+    text = lockscreen.quote(cfg, subject=args.subject, domain=args.domain,
+                            source=args.source, seed=args.seed,
+                            show_note=args.note)
+    if text is None:
+        print("No quotes stored yet — run: hyprmuse add \"Franz Kafka\"")
+        return 0
+    print(text)
+    return 0
+
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="hyprmuse",
+        description="Random quotes from musicians, authors and poets, for hyprlock.")
+    sub = p.add_subparsers(dest="cmd")
+
+    def add_search_flags(sp):
+        sp.add_argument("--source", default="", choices=sorted(REGISTRY) + [""],
+                        help="restrict to one source (default: try all)")
+        sp.add_argument("--lang", default="en",
+                        help="language edition, for wikiquote (e.g. de)")
+
+    sp = sub.add_parser("add", help="harvest a new subject")
+    sp.add_argument("query")
+    add_search_flags(sp)
+    sp.add_argument("--yes", "-y", action="store_true",
+                    help="take the best match without prompting")
+    sp.set_defaults(func=cmd_add)
+
+    sp = sub.add_parser("search", help="look up subjects without harvesting")
+    sp.add_argument("query")
+    add_search_flags(sp)
+    sp.set_defaults(func=cmd_search)
+
+    sp = sub.add_parser("list", help="show stored subjects")
+    sp.set_defaults(func=cmd_list)
+
+    sp = sub.add_parser("remove", help="delete a stored subject")
+    sp.add_argument("token", help="source:id or part of the name")
+    sp.set_defaults(func=cmd_remove)
+
+    sp = sub.add_parser("update", help="re-harvest stored subjects")
+    sp.add_argument("token", nargs="?", default="")
+    sp.add_argument("--all", action="store_true")
+    sp.set_defaults(func=cmd_update)
+
+    sp = sub.add_parser("sources", help="list available sources")
+    sp.set_defaults(func=cmd_sources)
+
+
+    sp = sub.add_parser("quote", help="print a random quote (default command)")
+    sp.add_argument("--lines", type=int, default=None,
+                    help="lines to take from sliceable items")
+    sp.add_argument("--width", type=int, default=None, help="wrap width, 0 disables")
+    sp.add_argument("--max-lines", type=int, default=None,
+                    help="most lines after wrapping; shorter picks are preferred")
+    sp.add_argument("--max-chars", type=int, default=None,
+                    help="most characters after wrapping, 0 disables")
+    sp.add_argument("--subject", default="", help="restrict to one subject")
+    sp.add_argument("--domain", default="", help="restrict to a domain")
+    sp.add_argument("--source", default="", help="restrict to a source")
+    sp.add_argument("--note", action="store_true", help="include the citation note")
+    sp.add_argument("--seed", type=int, default=None, help="deterministic pick")
+    sp.set_defaults(func=cmd_quote)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Bare `hyprmuse` prints a quote, so hyprlock can call it with no arguments.
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help")):
+        argv.insert(0, "quote")
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        return 130
+    except SourceError as exc:
+        return _err(str(exc))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyprmuse-0.3.2/hyprmuse/config.py

@@ -0,0 +1,46 @@
+"""XDG paths and user configuration."""
+
+import os
+import tomllib
+from pathlib import Path
+
+APP = "hyprmuse"
+
+
+def _xdg(env: str, fallback: str) -> Path:
+    root = os.environ.get(env)
+    return (Path(root) if root else Path.home() / fallback) / APP
+
+
+DATA_DIR = _xdg("XDG_DATA_HOME", ".local/share")
+CONFIG_DIR = _xdg("XDG_CONFIG_HOME", ".config")
+SUBJECTS_DIR = DATA_DIR / "subjects"
+RECENT_FILE = DATA_DIR / "recent.json"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+DEFAULTS = {
+    "lines": 3,
+    "width": 60,
+    "max_lines": 6,
+    "max_chars": 0,  # total characters after wrapping, 0 = unlimited
+    "weighting": "subject",  # "subject" or "quote"
+    "avoid_repeats": 20,
+    "min_line_chars": 2,  # lines shorter than this ("-", "I") are skipped when slicing
+}
+
+
+def load_config() -> dict:
+    """Merge config.toml over DEFAULTS. Missing or broken file falls back cleanly."""
+    cfg = dict(DEFAULTS)
+    cfg["subjects"] = {}
+    if not CONFIG_FILE.exists():
+        return cfg
+    try:
+        raw = tomllib.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return cfg
+    for key in DEFAULTS:
+        if key in raw.get("quote", {}):
+            cfg[key] = raw["quote"][key]
+    cfg["subjects"] = raw.get("subjects", {})
+    return cfg