notesctl 1.0.0__py3-none-any.whl

notesctl/__init__.py

@@ -0,0 +1,3 @@
+"""iCloud Notes to Markdown Exporter."""
+
+__version__ = "1.0.0"

notesctl/cli.py

@@ -0,0 +1,285 @@
+"""Command-line interface for notesctl."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+from .exporter import ExportOptions, NotesExporter
+
+app = typer.Typer(
+    name="notesctl",
+    help="Export Apple iCloud Notes to Markdown files.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def export(
+    output: Annotated[
+        Path,
+        typer.Option(
+            "-o",
+            "--output",
+            help="Output directory for exported notes",
+        ),
+    ] = Path("./notes-export"),
+    folder: Annotated[
+        str | None,
+        typer.Option(
+            "--folder",
+            "-f",
+            help="Only export notes from this folder",
+        ),
+    ] = None,
+    include_trashed: Annotated[
+        bool,
+        typer.Option(
+            "--include-trashed",
+            help="Include notes in trash",
+        ),
+    ] = False,
+    no_frontmatter: Annotated[
+        bool,
+        typer.Option(
+            "--no-frontmatter",
+            help="Don't include YAML frontmatter",
+        ),
+    ] = False,
+    flat: Annotated[
+        bool,
+        typer.Option(
+            "--flat",
+            help="Don't organize by folder",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            "-n",
+            help="Preview what would be exported without writing files",
+        ),
+    ] = False,
+    db_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--db",
+            help="Path to NoteStore.sqlite (uses default if not specified)",
+            hidden=True,
+        ),
+    ] = None,
+) -> None:
+    """Export Apple Notes to Markdown files."""
+    exporter = NotesExporter(db_path)
+
+    options = ExportOptions(
+        output_dir=output.expanduser().resolve(),
+        folder_name=folder,
+        include_trashed=include_trashed,
+        include_frontmatter=not no_frontmatter,
+        dry_run=dry_run,
+        organize_by_folder=not flat,
+    )
+
+    if dry_run:
+        console.print("[yellow]DRY RUN[/yellow] - No files will be written\n")
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            result = exporter.export(options, progress)
+    except FileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+    # Print results
+    console.print()
+    if dry_run:
+        console.print(f"[bold]Would export {result.exported_notes} notes[/bold]")
+        if result.exported_files:
+            console.print("\nFiles that would be created:")
+            for f in result.exported_files[:20]:
+                console.print(f"  {f}")
+            if len(result.exported_files) > 20:
+                console.print(f"  ... and {len(result.exported_files) - 20} more")
+    else:
+        console.print(f"[green]Exported {result.exported_notes} notes[/green]")
+        console.print(f"  Output: {result.output_path}")
+        console.print(f"  Attachments copied: {result.attachments_copied}")
+
+    if result.skipped_encrypted:
+        console.print(f"[yellow]Skipped {result.skipped_encrypted} encrypted notes[/yellow]")
+
+    if result.skipped_errors:
+        console.print(f"[red]Failed to export {result.skipped_errors} notes[/red]")
+
+    if result.errors:
+        console.print("\n[red]Errors:[/red]")
+        for error in result.errors[:10]:
+            console.print(f"  {error}")
+
+
+@app.command("list-notes")
+def list_notes(
+    folder: Annotated[
+        str | None,
+        typer.Option(
+            "--folder",
+            "-f",
+            help="Only list notes from this folder",
+        ),
+    ] = None,
+    include_trashed: Annotated[
+        bool,
+        typer.Option(
+            "--include-trashed",
+            help="Include notes in trash",
+        ),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit",
+            "-l",
+            help="Maximum number of notes to show",
+        ),
+    ] = 50,
+    db_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--db",
+            help="Path to NoteStore.sqlite",
+            hidden=True,
+        ),
+    ] = None,
+) -> None:
+    """List notes in the database."""
+    exporter = NotesExporter(db_path)
+
+    try:
+        notes = exporter.list_notes(folder, include_trashed)
+    except FileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+    if not notes:
+        console.print("No notes found.")
+        return
+
+    table = Table(title=f"Notes ({len(notes)} total)")
+    table.add_column("Title", style="cyan", no_wrap=True, max_width=50)
+    table.add_column("Folder", style="green")
+    table.add_column("Modified", style="yellow")
+    table.add_column("Status", style="dim")
+
+    for note in notes[:limit]:
+        status_parts = []
+        if note.is_encrypted:
+            status_parts.append("🔒")
+        if note.is_pinned:
+            status_parts.append("📌")
+        if note.is_trashed:
+            status_parts.append("🗑️")
+
+        table.add_row(
+            note.title[:50],
+            note.folder,
+            note.modified.strftime("%Y-%m-%d %H:%M"),
+            " ".join(status_parts),
+        )
+
+    console.print(table)
+
+    if len(notes) > limit:
+        console.print(
+            f"\n[dim]Showing {limit} of {len(notes)} notes. Use --limit to see more.[/dim]"
+        )
+
+
+@app.command("list-folders")
+def list_folders(
+    db_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--db",
+            help="Path to NoteStore.sqlite",
+            hidden=True,
+        ),
+    ] = None,
+) -> None:
+    """List all folders in Notes."""
+    exporter = NotesExporter(db_path)
+
+    try:
+        folders = exporter.list_folders()
+    except FileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+    if not folders:
+        console.print("No folders found.")
+        return
+
+    table = Table(title="Notes Folders")
+    table.add_column("Folder", style="cyan")
+    table.add_column("Notes", style="green", justify="right")
+
+    for name, count in sorted(folders, key=lambda x: x[0].lower()):
+        table.add_row(name, str(count))
+
+    console.print(table)
+
+
+@app.command("stats")
+def stats(
+    db_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--db",
+            help="Path to NoteStore.sqlite",
+            hidden=True,
+        ),
+    ] = None,
+) -> None:
+    """Show statistics about your Notes database."""
+    exporter = NotesExporter(db_path)
+
+    try:
+        db_stats = exporter.get_stats()
+    except FileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+    console.print("[bold]Notes Database Statistics[/bold]\n")
+    console.print(f"  Total notes: {db_stats['total_notes']}")
+    console.print(f"  Encrypted notes: {db_stats['encrypted_notes']}")
+    console.print(f"  Exportable: {db_stats['total_notes'] - db_stats['encrypted_notes']}")
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

notesctl/converter/__init__.py

@@ -0,0 +1,5 @@
+"""Converters for note content."""
+
+from .markdown import MarkdownConverter
+
+__all__ = ["MarkdownConverter"]

notesctl/converter/markdown.py

@@ -0,0 +1,232 @@
+"""Convert parsed notes to Markdown format."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ..database.models import Attachment, Note
+from ..parser.note_parser import Paragraph, ParsedNote, StyleType, TextRun
+
+
+@dataclass
+class MarkdownOptions:
+    """Options for Markdown conversion."""
+
+    include_frontmatter: bool = True
+    include_title_heading: bool = True
+    attachment_folder: str = "attachments"
+
+
+class MarkdownConverter:
+    """Convert parsed notes to Markdown format."""
+
+    def __init__(self, options: MarkdownOptions | None = None):
+        """Initialize converter with options."""
+        self.options = options or MarkdownOptions()
+
+    def convert(
+        self,
+        note: Note,
+        parsed: ParsedNote,
+        attachments: list[Attachment] | None = None,
+    ) -> str:
+        """
+        Convert a parsed note to Markdown.
+
+        Args:
+            note: Note metadata from database
+            parsed: Parsed note content
+            attachments: Optional list of attachments
+
+        Returns:
+            Markdown string
+        """
+        parts: list[str] = []
+
+        # YAML frontmatter
+        if self.options.include_frontmatter:
+            parts.append(self._generate_frontmatter(note))
+            parts.append("")  # Blank line after frontmatter
+
+        # Title as heading
+        if self.options.include_title_heading:
+            parts.append(f"# {note.title}")
+            parts.append("")
+
+        # Convert paragraphs
+        attachment_map = {a.identifier: a for a in (attachments or [])}
+        converted_paragraphs = self._convert_paragraphs(parsed.paragraphs, attachment_map)
+        parts.extend(converted_paragraphs)
+
+        return "\n".join(parts)
+
+    def _generate_frontmatter(self, note: Note) -> str:
+        """Generate YAML frontmatter."""
+        lines = ["---"]
+        lines.append(f'title: "{self._escape_yaml_string(note.title)}"')
+        lines.append(f"created: {self._format_datetime(note.created)}")
+        lines.append(f"modified: {self._format_datetime(note.modified)}")
+        lines.append(f'folder: "{self._escape_yaml_string(note.folder)}"')
+
+        if note.is_pinned:
+            lines.append("pinned: true")
+
+        lines.append("---")
+        return "\n".join(lines)
+
+    def _escape_yaml_string(self, s: str) -> str:
+        """Escape a string for YAML."""
+        return s.replace("\\", "\\\\").replace('"', '\\"')
+
+    def _format_datetime(self, dt: datetime) -> str:
+        """Format datetime for frontmatter."""
+        return dt.strftime("%Y-%m-%dT%H:%M:%S")
+
+    def _convert_paragraphs(
+        self,
+        paragraphs: list[Paragraph],
+        attachment_map: dict[str, Attachment],
+    ) -> list[str]:
+        """Convert paragraphs to Markdown lines."""
+        lines: list[str] = []
+        prev_style: StyleType | None = None
+        in_list = False
+
+        for para in paragraphs:
+            # Handle list transitions - add blank line before new list
+            is_list = (
+                para.style
+                in (
+                    StyleType.DOTTED_LIST,
+                    StyleType.DASHED_LIST,
+                    StyleType.NUMBERED_LIST,
+                    StyleType.CHECKLIST,
+                )
+                or para.is_checklist
+            )
+
+            should_add_blank = (is_list and not in_list and lines and lines[-1]) or (
+                not is_list and in_list and lines and lines[-1]
+            )
+            if should_add_blank:
+                lines.append("")
+
+            in_list = is_list
+
+            # Skip empty paragraphs but preserve blank lines
+            # But don't skip paragraphs with attachments
+            has_attachment = any(run.attachment_id for run in para.runs)
+            if not para.runs or (not para.plain_text.strip() and not has_attachment):
+                if lines and lines[-1] != "":
+                    lines.append("")
+                continue
+
+            line = self._convert_paragraph(para, attachment_map, prev_style)
+            lines.append(line)
+            prev_style = para.style
+
+        # Clean up trailing empty lines
+        while lines and lines[-1] == "":
+            lines.pop()
+
+        return lines
+
+    def _convert_paragraph(
+        self,
+        para: Paragraph,
+        attachment_map: dict[str, Attachment],
+        prev_style: StyleType | None,  # noqa: ARG002
+    ) -> str:
+        """Convert a single paragraph to Markdown."""
+        # Get formatted text content
+        text = self._format_runs(para.runs, attachment_map)
+
+        # Apply paragraph-level formatting
+        if para.style == StyleType.TITLE:
+            return f"# {text}"
+        if para.style == StyleType.HEADING:
+            return f"## {text}"
+        if para.style == StyleType.SUBHEADING:
+            return f"### {text}"
+        if para.style == StyleType.MONOSPACED:
+            return f"`{text}`"
+        if para.style in {StyleType.DOTTED_LIST, StyleType.DASHED_LIST}:
+            indent = "  " * para.indent
+            return f"{indent}- {text}"
+        if para.style == StyleType.NUMBERED_LIST:
+            indent = "  " * para.indent
+            num = para.list_item_number or 1
+            return f"{indent}{num}. {text}"
+        if para.is_checklist or para.style == StyleType.CHECKLIST:
+            indent = "  " * para.indent
+            checkbox = "[x]" if para.checklist_checked else "[ ]"
+            return f"{indent}- {checkbox} {text}"
+        if para.is_blockquote:
+            return f"> {text}"
+        return text
+
+    def _format_runs(
+        self,
+        runs: list[TextRun],
+        attachment_map: dict[str, Attachment],
+    ) -> str:
+        """Format text runs with inline Markdown."""
+        parts: list[str] = []
+
+        for run in runs:
+            text = run.text
+
+            # Handle attachment
+            if run.attachment_id:
+                attachment = attachment_map.get(run.attachment_id)
+                if attachment and attachment.is_image:
+                    # Use relative path for images
+                    filename = attachment.filename or f"{run.attachment_id}.jpg"
+                    img_path = f"{self.options.attachment_folder}/{run.attachment_id}/{filename}"
+                    parts.append(f"![{filename}]({img_path})")
+                    continue
+                if attachment:
+                    # Non-image attachment
+                    filename = attachment.filename or run.attachment_id
+                    att_path = f"{self.options.attachment_folder}/{run.attachment_id}/{filename}"
+                    parts.append(f"[{filename}]({att_path})")
+                    continue
+
+            # Skip empty text
+            if not text:
+                continue
+
+            # Apply inline formatting (order matters for nesting)
+            formatted = text
+
+            # Escape Markdown special characters in regular text
+            if not run.monospace:
+                formatted = self._escape_markdown(formatted)
+
+            # Apply formatting
+            if run.monospace:
+                formatted = f"`{formatted}`"
+            if run.bold:
+                formatted = f"**{formatted}**"
+            if run.italic:
+                formatted = f"*{formatted}*"
+            if run.strikethrough:
+                formatted = f"~~{formatted}~~"
+            if run.underline:
+                # Markdown doesn't have native underline, use HTML
+                formatted = f"<u>{formatted}</u>"
+            if run.link:
+                formatted = f"[{formatted}]({run.link})"
+
+            parts.append(formatted)
+
+        return "".join(parts)
+
+    def _escape_markdown(self, text: str) -> str:
+        """Escape Markdown special characters."""
+        # Only escape characters that would be interpreted as Markdown
+        # Be conservative to avoid over-escaping
+        chars_to_escape = ["\\", "`", "*", "_", "[", "]", "#"]
+        result = text
+        for char in chars_to_escape:
+            result = result.replace(char, f"\\{char}")
+        return result

notesctl/database/__init__.py

@@ -0,0 +1,7 @@
+"""Database access layer for Apple Notes SQLite database."""
+
+from .connection import SafeNotesDatabase
+from .models import Attachment, Folder, Note
+from .queries import NotesQueries
+
+__all__ = ["Attachment", "Folder", "Note", "NotesQueries", "SafeNotesDatabase"]

notesctl/database/connection.py

@@ -0,0 +1,156 @@
+"""Safe read-only database connection for Apple Notes."""
+
+import shutil
+import sqlite3
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console()
+
+# Default location of the Apple Notes database
+DEFAULT_NOTES_DB = Path.home() / "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
+
+
+class SafeNotesDatabase:
+    """
+    Safe read-only access to Apple Notes SQLite database.
+
+    Safety measures:
+    1. Copies database + WAL + SHM to temp directory before reading
+    2. Opens database in read-only mode using SQLite URI
+    3. All queries are SELECT-only (enforced by this class)
+    """
+
+    def __init__(self, db_path: Path | None = None):
+        """
+        Initialize the database connection wrapper.
+
+        Args:
+            db_path: Path to the NoteStore.sqlite file. Uses default if not provided.
+        """
+        self.source_path = db_path or DEFAULT_NOTES_DB
+        self._temp_dir: tempfile.TemporaryDirectory[str] | None = None
+        self._temp_db_path: Path | None = None
+        self._connection: sqlite3.Connection | None = None
+
+    def _verify_source_exists(self) -> None:
+        """Verify the source database exists."""
+        if not self.source_path.exists():
+            raise FileNotFoundError(
+                f"Notes database not found at {self.source_path}. "
+                "Make sure you have Apple Notes installed and have created at least one note."
+            )
+
+    def _copy_database_files(self) -> Path:
+        """
+        Copy database and associated files to temp directory.
+
+        Returns:
+            Path to the copied database file.
+        """
+        self._temp_dir = tempfile.TemporaryDirectory(prefix="notes_export_")
+        temp_path = Path(self._temp_dir.name)
+
+        # Copy main database file
+        db_name = self.source_path.name
+        dest_db = temp_path / db_name
+        shutil.copy2(self.source_path, dest_db)
+
+        # Copy WAL and SHM files if they exist (important for transaction consistency)
+        for suffix in ["-wal", "-shm"]:
+            wal_file = self.source_path.parent / f"{db_name}{suffix}"
+            if wal_file.exists():
+                shutil.copy2(wal_file, temp_path / f"{db_name}{suffix}")
+
+        return dest_db
+
+    def connect(self) -> None:
+        """
+        Establish a safe read-only connection to the database.
+
+        This copies the database to a temp directory and opens it read-only.
+        """
+        self._verify_source_exists()
+        self._temp_db_path = self._copy_database_files()
+
+        # Open in read-only mode using SQLite URI
+        # The mode=ro parameter ensures SQLite won't write to the file
+        uri = f"file:{self._temp_db_path}?mode=ro"
+        self._connection = sqlite3.connect(uri, uri=True)
+        self._connection.row_factory = sqlite3.Row
+
+    def close(self) -> None:
+        """Close the database connection and clean up temp files."""
+        if self._connection:
+            self._connection.close()
+            self._connection = None
+        if self._temp_dir:
+            self._temp_dir.cleanup()
+            self._temp_dir = None
+            self._temp_db_path = None
+
+    @property
+    def connection(self) -> sqlite3.Connection:
+        """Get the active database connection."""
+        if self._connection is None:
+            raise RuntimeError("Database not connected. Call connect() first.")
+        return self._connection
+
+    def execute(self, query: str, params: tuple = ()) -> sqlite3.Cursor:
+        """
+        Execute a SELECT query safely.
+
+        Args:
+            query: SQL query (must be SELECT only)
+            params: Query parameters
+
+        Returns:
+            Cursor with query results
+
+        Raises:
+            ValueError: If query is not a SELECT statement
+        """
+        # Safety check: only allow SELECT queries
+        normalized = query.strip().upper()
+        if not normalized.startswith("SELECT"):
+            raise ValueError("Only SELECT queries are allowed for safety")
+
+        return self.connection.execute(query, params)
+
+    def fetchall(self, query: str, params: tuple = ()) -> list[sqlite3.Row]:
+        """Execute a query and fetch all results."""
+        return self.execute(query, params).fetchall()
+
+    def fetchone(self, query: str, params: tuple = ()) -> sqlite3.Row | None:
+        """Execute a query and fetch one result."""
+        return self.execute(query, params).fetchone()
+
+    def __enter__(self) -> "SafeNotesDatabase":
+        """Context manager entry."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit."""
+        self.close()
+
+
+@contextmanager
+def get_notes_database(db_path: Path | None = None) -> Iterator[SafeNotesDatabase]:
+    """
+    Context manager for safe database access.
+
+    Usage:
+        with get_notes_database() as db:
+            notes = db.fetchall("SELECT * FROM notes")
+    """
+    db = SafeNotesDatabase(db_path)
+    try:
+        db.connect()
+        yield db
+    finally:
+        db.close()