bearcli 1.2.0__tar.gz → 1.3.0__tar.gz

{bearcli-1.2.0 → bearcli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bearcli
-Version: 1.2.0
+Version: 1.3.0
 Summary: The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal
 Keywords: bear,notes,cli,markdown,macos
 Author: Michel Tricot
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
 Requires-Dist: detect-secrets>=1.5.0
 Requires-Dist: rapidfuzz>=3.14.5
+Requires-Dist: textual>=8.2.8
 Requires-Dist: typer>=0.27.0
 Requires-Python: >=3.13
 Project-URL: Documentation, https://github.com/michel-tricot/bearcli/blob/main/docs/IMPLEMENTATION.md
@@ -23,9 +24,9 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-# 🐻 bearcli
+# 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** — read, search, export, and
+**The missing CLI for [Bear](https://bear.app) notes** - read, search, export, and
 manage your notes from the terminal.
 
 [![CI](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml/badge.svg)](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml)
@@ -79,6 +80,8 @@ bearcli get C44D09DC-... --meta              # with YAML-style frontmatter
 bearcli get C44D09DC-... -r                  # rewrite attachment refs to absolute paths
 bearcli get C44D09DC-... --redact-secrets    # secrets replaced by placeholders
 bearcli open C44D09DC-...                    # open in the Bear app
+bearcli browse                               # interactive: type to filter, Enter opens
+bearcli stats                                # counts, words, top tags, notes per year
 ```
 
 ### Search
@@ -90,7 +93,7 @@ bearcli search "quarterly planing" --fuzzy   # typo-tolerant, ranked by score
 
 ### Write
 
-Writes go through Bear's x-callback-url API — the database itself is never
+Writes go through Bear's x-callback-url API - the database itself is never
 written. These launch the Bear app if needed.
 
 ```sh
@@ -115,20 +118,28 @@ bearcli tag delete old-name                  # across all notes (asks first)
 
 ### Export
 
-Every note becomes a self-contained directory — `<slug>/README.md` plus its
-attachments — with a generated index, so GitHub renders the whole export as a
+Every note becomes a self-contained directory - `<slug>/README.md` plus its
+attachments - with a generated index, so GitHub renders the whole export as a
 browsable tree.
 
 Before anything is written, the notes are scanned for potential secrets
-(token formats, key blocks, credential assignments); findings block the export
-with a list of the affected notes (`--allow-secrets` overrides).
+(token formats, key blocks, credential assignments, high-entropy strings);
+findings block the export with a list of the affected notes. Override with
+`--allow-secrets` (export as-is) or `--redact-secrets` (replace each secret
+with a `[redacted: <rule>]` placeholder - notes in Bear are untouched).
+
+> **⚠️ Warning** - detection and redaction are best-effort: a secret that
+> reads like ordinary text (a password written as prose, an account number)
+> will not be caught. Ideally, don't keep secrets in notes at all - use a
+> password manager, or at least Bear's encrypted notes, which never leave
+> the app.
 
 ```sh
 bearcli export ~/bear-backup
 bearcli export ~/bear-backup --sync          # only rewrite notes that changed
 bearcli export ~/bear-backup --redact-secrets  # secrets become [redacted: <rule>]
 
-# Mirror to a git repository (clone it first; use a *private* repo — these are
+# Mirror to a git repository (clone it first; use a *private* repo - these are
 # your notes). Bear is the source of truth: remote or manual edits are kept in
 # git history but overwritten in HEAD. Never force-pushes, never gets stuck.
 git clone git@github.com:you/bear-notes.git ~/bear-notes
@@ -150,6 +161,16 @@ defaults to Bear's standard location and can be overridden with `--db` or the
 `BEAR_DB_PATH` environment variable. Encrypted notes are listed but their
 content cannot be read.
 
+## Agent skill
+
+An [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
+teaching AI agents (Claude Code, etc.) how to use `bearcli` ships in
+[`skills/bear-notes`](skills/bear-notes/SKILL.md):
+
+```sh
+cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+```
+
 ## Development
 
 ```sh

{bearcli-1.2.0 → bearcli-1.3.0}/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-# 🐻 bearcli
+# 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** — read, search, export, and
+**The missing CLI for [Bear](https://bear.app) notes** - read, search, export, and
 manage your notes from the terminal.
 
 [![CI](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml/badge.svg)](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml)
@@ -56,6 +56,8 @@ bearcli get C44D09DC-... --meta              # with YAML-style frontmatter
 bearcli get C44D09DC-... -r                  # rewrite attachment refs to absolute paths
 bearcli get C44D09DC-... --redact-secrets    # secrets replaced by placeholders
 bearcli open C44D09DC-...                    # open in the Bear app
+bearcli browse                               # interactive: type to filter, Enter opens
+bearcli stats                                # counts, words, top tags, notes per year
 ```
 
 ### Search
@@ -67,7 +69,7 @@ bearcli search "quarterly planing" --fuzzy   # typo-tolerant, ranked by score
 
 ### Write
 
-Writes go through Bear's x-callback-url API — the database itself is never
+Writes go through Bear's x-callback-url API - the database itself is never
 written. These launch the Bear app if needed.
 
 ```sh
@@ -92,20 +94,28 @@ bearcli tag delete old-name                  # across all notes (asks first)
 
 ### Export
 
-Every note becomes a self-contained directory — `<slug>/README.md` plus its
-attachments — with a generated index, so GitHub renders the whole export as a
+Every note becomes a self-contained directory - `<slug>/README.md` plus its
+attachments - with a generated index, so GitHub renders the whole export as a
 browsable tree.
 
 Before anything is written, the notes are scanned for potential secrets
-(token formats, key blocks, credential assignments); findings block the export
-with a list of the affected notes (`--allow-secrets` overrides).
+(token formats, key blocks, credential assignments, high-entropy strings);
+findings block the export with a list of the affected notes. Override with
+`--allow-secrets` (export as-is) or `--redact-secrets` (replace each secret
+with a `[redacted: <rule>]` placeholder - notes in Bear are untouched).
+
+> **⚠️ Warning** - detection and redaction are best-effort: a secret that
+> reads like ordinary text (a password written as prose, an account number)
+> will not be caught. Ideally, don't keep secrets in notes at all - use a
+> password manager, or at least Bear's encrypted notes, which never leave
+> the app.
 
 ```sh
 bearcli export ~/bear-backup
 bearcli export ~/bear-backup --sync          # only rewrite notes that changed
 bearcli export ~/bear-backup --redact-secrets  # secrets become [redacted: <rule>]
 
-# Mirror to a git repository (clone it first; use a *private* repo — these are
+# Mirror to a git repository (clone it first; use a *private* repo - these are
 # your notes). Bear is the source of truth: remote or manual edits are kept in
 # git history but overwritten in HEAD. Never force-pushes, never gets stuck.
 git clone git@github.com:you/bear-notes.git ~/bear-notes
@@ -127,6 +137,16 @@ defaults to Bear's standard location and can be overridden with `--db` or the
 `BEAR_DB_PATH` environment variable. Encrypted notes are listed but their
 content cannot be read.
 
+## Agent skill
+
+An [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
+teaching AI agents (Claude Code, etc.) how to use `bearcli` ships in
+[`skills/bear-notes`](skills/bear-notes/SKILL.md):
+
+```sh
+cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+```
+
 ## Development
 
 ```sh

{bearcli-1.2.0 → bearcli-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bearcli"
-version = "1.2.0"
+version = "1.3.0"
 description = "The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal"
 readme = "README.md"
 keywords = ["bear", "notes", "cli", "markdown", "macos"]
@@ -20,6 +20,7 @@ requires-python = ">=3.13"
 dependencies = [
     "detect-secrets>=1.5.0",
     "rapidfuzz>=3.14.5",
+    "textual>=8.2.8",
     "typer>=0.27.0",
 ]
 
@@ -37,6 +38,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "pytest>=9.1.1",
     "ruff>=0.16.0",
     "ty>=0.0.64",
 ]

{bearcli-1.2.0 → bearcli-1.3.0}/src/bearcli/cli.py

@@ -841,3 +841,93 @@ _alias("search", "note search", search)
 _alias("get", "note get", get)
 _alias("open", "note open", open_note)
 _alias("create", "note create", create)
+
+
+@app.command()
+def stats(
+    fmt: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format: table or json."),
+    ] = OutputFormat.table,
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Show statistics about the note library."""
+    db = _open_db(db_path)
+    try:
+        notes = db.list_notes(limit=None, include_trashed=True, include_archived=True, with_text=True)
+        tag_counts = db.list_tags()
+        attachment_count, attachment_bytes = db.attachment_stats()
+    finally:
+        db.close()
+
+    active = [n for n in notes if not n.trashed and not n.archived]
+    by_year: dict[str, int] = {}
+    for n in notes:
+        if not n.trashed and n.created:
+            year = str(n.created.year)
+            by_year[year] = by_year.get(year, 0) + 1
+
+    data = {
+        "notes": len(notes),
+        "active": len(active),
+        "archived": sum(1 for n in notes if n.archived and not n.trashed),
+        "trashed": sum(1 for n in notes if n.trashed),
+        "pinned": sum(1 for n in notes if n.pinned and not n.trashed),
+        "encrypted": sum(1 for n in notes if n.encrypted and not n.trashed),
+        "words": sum(len((n.text or "").split()) for n in notes if not n.trashed),
+        "tags": len(tag_counts),
+        "attachments": attachment_count,
+        "attachment_bytes": attachment_bytes,
+        "notes_by_year": dict(sorted(by_year.items())),
+        "top_tags": [{"tag": t, "notes": c} for t, c in sorted(tag_counts, key=lambda tc: -tc[1])[:10]],
+    }
+
+    if fmt is OutputFormat.json:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    table = Table(box=box.ROUNDED, show_header=False)
+    table.add_column(style="bold")
+    table.add_column(justify="right")
+    table.add_row("Notes", str(data["notes"]))
+    table.add_row("  active", str(data["active"]))
+    table.add_row("  archived", str(data["archived"]))
+    table.add_row("  trashed", str(data["trashed"]))
+    table.add_row("  pinned", str(data["pinned"]))
+    table.add_row("  encrypted", str(data["encrypted"]))
+    table.add_row("Words", f"{data['words']:,}")
+    table.add_row("Tags", str(data["tags"]))
+    table.add_row("Attachments", f"{attachment_count} ({attachment_bytes / 1_000_000:.1f} MB)")
+    console.print(table)
+
+    if data["top_tags"]:
+        tag_table = Table(box=box.ROUNDED, header_style="bold")
+        tag_table.add_column("Top tags", style="cyan")
+        tag_table.add_column("Notes", justify="right")
+        for entry in data["top_tags"]:
+            tag_table.add_row(str(entry["tag"]), str(entry["notes"]))
+        console.print(tag_table)
+
+    year_table = Table(box=box.ROUNDED, header_style="bold")
+    year_table.add_column("Created", style="cyan")
+    year_table.add_column("Notes", justify="right")
+    for year, count in data["notes_by_year"].items():
+        year_table.add_row(year, str(count))
+    console.print(year_table)
+
+
+@app.command()
+def browse(
+    fuzzy: Annotated[bool, typer.Option("--fuzzy", help="Typo-tolerant ranked filtering.")] = False,
+    tag_filter: Annotated[str | None, typer.Option("--tag", "-t", help="Restrict to notes with this tag.")] = None,
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Browse notes interactively: type to filter, Enter opens the note in Bear."""
+    from bearcli.tui import browse as run_browser
+
+    db = _open_db(db_path)
+    try:
+        notes = db.list_notes(limit=None, tag=tag_filter, with_text=True)
+    finally:
+        db.close()
+    run_browser(notes, fuzzy=fuzzy)

{bearcli-1.2.0 → bearcli-1.3.0}/src/bearcli/db.py

@@ -144,6 +144,18 @@ class BearDB:
         ).fetchall()
         return [(row[0], row[1]) for row in rows]
 
+    def attachment_stats(self) -> tuple[int, int]:
+        """(count, total bytes) of attachments on non-deleted notes."""
+        row = self.conn.execute(
+            """
+            SELECT COUNT(*), COALESCE(SUM(f.ZFILESIZE), 0)
+            FROM ZSFNOTEFILE f
+            JOIN ZSFNOTE n ON n.Z_PK = f.ZNOTE
+            WHERE f.ZPERMANENTLYDELETED = 0 AND n.ZPERMANENTLYDELETED = 0 AND n.ZTRASHED = 0
+            """
+        ).fetchone()
+        return row[0], row[1]
+
     def _attachments_for_note(self, note_pk: int) -> list[Attachment]:
         rows = self.conn.execute(
             """

bearcli-1.3.0/src/bearcli/tui.py

@@ -0,0 +1,83 @@
+"""Interactive note browser (Textual)."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+
+from bearcli import actions
+from bearcli.db import Note
+from bearcli.search import naive_search, search_notes
+
+MAX_RESULTS = 50
+
+
+class BrowseApp(App):
+    """Type to filter, arrows to move, Enter to open in Bear, Esc to quit."""
+
+    CSS = """
+    #query { dock: top; }
+    #status { dock: bottom; height: 1; color: $text-muted; padding: 0 1; }
+    #results { height: 1fr; }
+    #preview { width: 45%; border-left: solid $surface; padding: 0 1; color: $text-muted; }
+    """
+    BINDINGS = [("escape", "quit", "Quit")]
+
+    def __init__(self, notes: list[Note], fuzzy: bool = False):
+        super().__init__()
+        self.notes = notes
+        self.fuzzy = fuzzy
+        self.shown: list[Note] = []
+
+    def compose(self) -> ComposeResult:
+        yield Input(placeholder="Search notes…", id="query")
+        with Horizontal():
+            yield OptionList(id="results")
+            yield Static(id="preview")
+        yield Static(id="status")
+
+    def on_mount(self) -> None:
+        self._refresh("")
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        self._refresh(event.value)
+
+    def _refresh(self, query: str) -> None:
+        if not query.strip():
+            self.shown = self.notes[:MAX_RESULTS]
+        elif self.fuzzy:
+            self.shown = [r.note for r in search_notes(self.notes, query)[:MAX_RESULTS]]
+        else:
+            self.shown = [r.note for r in naive_search(self.notes, query)[:MAX_RESULTS]]
+
+        results = self.query_one("#results", OptionList)
+        results.clear_options()
+        for note in self.shown:
+            date = note.modified.strftime("%Y-%m-%d") if note.modified else "          "
+            tags = f"  #{' #'.join(note.tags)}" if note.tags else ""
+            results.add_option(Option(f"{date}  {note.title}{tags}", id=note.id))
+        if self.shown:
+            results.highlighted = 0
+        self.query_one("#status", Static).update(
+            f"{len(self.shown)} shown / {len(self.notes)} notes · Enter: open in Bear · Esc: quit"
+        )
+
+    def on_option_list_option_highlighted(self, event: OptionList.OptionHighlighted) -> None:
+        note = next((n for n in self.shown if n.id == event.option_id), None)
+        preview = "\n".join((note.text or "").splitlines()[:40]) if note else ""
+        self.query_one("#preview", Static).update(preview)
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        if event.option_id:
+            actions.open_note(event.option_id)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        results = self.query_one("#results", OptionList)
+        if self.shown and results.highlighted is not None:
+            actions.open_note(self.shown[results.highlighted].id)
+
+
+def browse(notes: list[Note], fuzzy: bool = False) -> None:
+    BrowseApp(notes, fuzzy=fuzzy).run()