studyctl 2.0.0__py3-none-any.whl

studyctl/cli/_web.py

@@ -0,0 +1,228 @@
+"""Web, TUI, and docs commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.table import Table
+
+from studyctl.cli._shared import console
+
+
+def _find_docs_dir() -> Path:
+    """Find the docs directory relative to the package."""
+    candidate = Path(__file__).resolve().parent.parent
+    for _ in range(6):
+        if (candidate / "mkdocs.yml").exists():
+            return candidate / "docs"
+        candidate = candidate.parent
+    for p in [
+        Path.home() / "code" / "personal" / "tools" / "socratic-study-mentor" / "docs",
+        Path.home() / ".agents" / "shared",
+    ]:
+        if p.exists():
+            return p
+    msg = "Could not find docs directory. Run from the repo or set STUDYCTL_DOCS_DIR."
+    raise click.ClickException(msg)
+
+
+def _strip_markdown(text: str) -> str:
+    """Strip markdown formatting for TTS-friendly plain text."""
+    import re
+
+    text = re.sub(r"```[\s\S]*?```", "", text)
+    text = re.sub(r"`[^`]+`", "", text)
+    text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
+    text = re.sub(r"\*{1,3}([^*]+)\*{1,3}", r"\1", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = re.sub(r"^!!! \w+.*$", "", text, flags=re.MULTILINE)
+    text = re.sub(r"^\|.*\|$", "", text, flags=re.MULTILINE)
+    text = re.sub(r"^[-|: ]+$", "", text, flags=re.MULTILINE)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+@click.command()
+@click.option("--port", "-p", default=8567, help="Port for web server")
+@click.option("--lan", is_flag=True, help="Expose to LAN (default: localhost only)")
+def web(port: int, lan: bool) -> None:
+    """Launch the study PWA in your browser.
+
+    Serves flashcard and quiz review as a web app accessible from any
+    device on the network. Installable as a PWA (add to home screen).
+    Includes OpenDyslexic font toggle for accessibility.
+
+    Requires: uv pip install 'studyctl[web]'
+    """
+    try:
+        import uvicorn
+    except ImportError:
+        console.print(
+            "[red]The web server requires FastAPI.[/red]\nInstall: uv pip install 'studyctl[web]'"
+        )
+        return
+
+    import yaml
+
+    config_path = Path.home() / ".config" / "studyctl" / "config.yaml"
+    study_dirs: list[str] = []
+    if config_path.exists():
+        try:
+            data = yaml.safe_load(config_path.read_text()) or {}
+            study_dirs = data.get("review", {}).get("directories", [])
+        except Exception:
+            pass
+
+    from studyctl.web.app import create_app
+
+    host = "0.0.0.0" if lan else "127.0.0.1"
+    app = create_app(study_dirs=study_dirs)
+    console.print(f"[bold]Study PWA at http://{host}:{port}[/bold]")
+    if not lan:
+        console.print("[dim]Use --lan to expose to network[/dim]")
+    uvicorn.run(app, host=host, port=port, workers=1, log_level="warning")
+
+
+@click.command()
+def tui() -> None:
+    """Launch the interactive terminal dashboard (requires textual).
+
+    Install: uv pip install 'studyctl[tui]'
+
+    Key bindings: f=flashcards, z=quiz, d=dashboard, q=quit, v=voice, o=OpenDyslexic
+
+    For a web-based UI accessible from any device, use: studyctl web
+    """
+    try:
+        from studyctl.tui.app import StudyApp
+    except ImportError:
+        console.print(
+            "[red]The TUI requires 'textual'.[/red]\nInstall: uv pip install 'studyctl[tui]'"
+        )
+        return
+
+    import yaml
+
+    config_path = Path.home() / ".config" / "studyctl" / "config.yaml"
+    study_dirs: list[str] = []
+    theme: str = ""
+    dyslexic: bool = False
+    if config_path.exists():
+        try:
+            data = yaml.safe_load(config_path.read_text()) or {}
+            study_dirs = data.get("review", {}).get("directories", [])
+            tui_cfg = data.get("tui", {})
+            theme = tui_cfg.get("theme", "")
+            dyslexic = tui_cfg.get("dyslexic_friendly", False)
+        except Exception:
+            pass
+
+    app = StudyApp(
+        study_dirs=study_dirs,
+        theme_name=theme,
+        dyslexic_friendly=dyslexic,
+    )
+    app.run()
+
+
+# --- Docs commands ---
+
+
+@click.group(name="docs")
+def docs_group() -> None:
+    """Browse and read documentation."""
+
+
+@docs_group.command(name="serve")
+@click.option("--port", "-p", default=8000, help="Port for local server")
+def docs_serve(port: int) -> None:
+    """Serve documentation site locally and open in browser."""
+    import subprocess
+
+    repo_root = _find_docs_dir().parent
+    console.print(f"[bold]Serving docs at http://localhost:{port}[/bold]")
+    subprocess.run(["mkdocs", "serve", "-a", f"localhost:{port}"], cwd=str(repo_root), check=False)
+
+
+@docs_group.command(name="open")
+def docs_open() -> None:
+    """Build and open documentation in browser."""
+    import subprocess
+    import webbrowser
+
+    repo_root = _find_docs_dir().parent
+    site_dir = repo_root / "site"
+    console.print("Building docs...")
+    subprocess.run(["mkdocs", "build"], cwd=str(repo_root), check=True, capture_output=True)
+    index = site_dir / "index.html"
+    if index.exists():
+        webbrowser.open(f"file://{index}")
+        console.print("[green]Opened docs in browser[/green]")
+    else:
+        console.print("[red]Build failed \u2014 site/index.html not found[/red]")
+
+
+@docs_group.command(name="list")
+def docs_list() -> None:
+    """List available documentation pages."""
+    docs_dir = _find_docs_dir()
+    table = Table(title="Documentation Pages")
+    table.add_column("Page", style="bold")
+    table.add_column("Title")
+    for md in sorted(docs_dir.glob("*.md")):
+        title = md.stem.replace("-", " ").title()
+        for line in md.read_text().splitlines():
+            if line.startswith("# "):
+                title = line[2:].strip()
+                break
+        table.add_row(md.stem, title)
+    console.print(table)
+
+
+@docs_group.command(name="read")
+@click.argument("page")
+def docs_read(page: str) -> None:
+    """Read a documentation page aloud using study-speak.
+
+    PAGE is the doc name without .md extension (e.g. 'voice-output', 'audhd-learning-philosophy').
+    Use 'studyctl docs list' to see available pages.
+    """
+    import subprocess
+
+    docs_dir = _find_docs_dir()
+    md_file = docs_dir / f"{page}.md"
+    if not md_file.exists():
+        matches = [f for f in docs_dir.glob("*.md") if page.lower() in f.stem.lower()]
+        if len(matches) == 1:
+            md_file = matches[0]
+        else:
+            console.print(
+                f"[red]Page '{page}' not found.[/red] Run [bold]studyctl docs list[/bold]"
+            )
+            return
+
+    text = _strip_markdown(md_file.read_text())
+    if not text:
+        console.print("[yellow]Page is empty after stripping markdown.[/yellow]")
+        return
+
+    speak_bin = Path.home() / ".local" / "bin" / "study-speak"
+    if not speak_bin.exists():
+        console.print(
+            "[red]study-speak not installed.[/red]"
+            " Run: uv tool install './packages/agent-session-tools[tts]'"
+        )
+        return
+
+    console.print(f"[bold]\U0001f4d6 Reading: {md_file.stem}[/bold]")
+    console.print(f"[dim]({len(text.split())} words \u2014 press Ctrl+C to stop)[/dim]\n")
+
+    try:
+        subprocess.run([str(speak_bin), text], check=True, timeout=300)
+        console.print("\n[green]\u2713 Done reading[/green]")
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopped reading[/yellow]")
+    except subprocess.TimeoutExpired:
+        console.print("\n[yellow]Reading timed out[/yellow]")

studyctl/content/__init__.py

@@ -0,0 +1,5 @@
+"""Content pipeline -- absorbed from pdf-by-chapters.
+
+Provides PDF splitting, NotebookLM integration, syllabus generation,
+markdown conversion, and course-centric storage management.
+"""

studyctl/content/markdown_converter.py

@@ -0,0 +1,271 @@
+"""Markdown to PDF conversion with mermaid diagram rendering."""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_WIKILINK_RE = re.compile(r"\[\[([^\]|]+)(?:\|([^\]]+))?\]\]")
+_FRONTMATTER_RE = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
+_MERMAID_BLOCK_RE = re.compile(r"```mermaid\s*\n(.*?)```", re.DOTALL)
+
+
+class ConversionError(Exception):
+    """Raised when markdown to PDF conversion fails."""
+
+
+def check_prerequisites() -> list[str]:
+    """Check that pandoc and mmdc are installed.
+
+    Returns:
+        List of missing tool names. Empty if all present.
+    """
+    missing = []
+    if not shutil.which("pandoc"):
+        missing.append("pandoc")
+    if not shutil.which("mmdc"):
+        missing.append("mmdc (@mermaid-js/mermaid-cli)")
+    if not shutil.which("typst"):
+        missing.append("typst (brew install typst)")
+    return missing
+
+
+def preprocess_markdown(content: str) -> str:
+    """Clean markdown for pandoc conversion.
+
+    Strips YAML frontmatter and converts Obsidian wikilinks to plain text.
+
+    Args:
+        content: Raw markdown file content.
+
+    Returns:
+        Cleaned markdown ready for pandoc.
+    """
+    content = _FRONTMATTER_RE.sub("", content)
+    content = _WIKILINK_RE.sub(lambda m: m.group(2) or m.group(1), content)
+    return content
+
+
+# Matches unquoted node labels containing / (file paths), e.g. C[/home/user]
+# but NOT already-quoted labels like C["some text"]
+_UNQUOTED_PATH_NODE_RE = re.compile(r'\[(/[^\]"]+)\]')
+
+# Matches <br/> or <br> in text (not valid in all mermaid contexts)
+_HTML_BR_RE = re.compile(r"<br\s*/?>")
+
+
+def _sanitize_mermaid(code: str) -> str:
+    """Fix common mermaid syntax issues that cause parser failures.
+
+    Fixes:
+    - Unquoted node labels containing / (file paths) -> wraps in quotes
+    - <br/> tags in state diagram notes -> replaced with newline character
+    """
+    # Wrap unquoted path-like node labels in quotes: [/home/user] -> ["/home/user"]
+    code = _UNQUOTED_PATH_NODE_RE.sub(lambda m: f'["{m.group(1)}"]', code)
+
+    # Replace <br/> with space -- special separators (|, /, \n) break state diagram notes
+    code = _HTML_BR_RE.sub(" ", code)
+
+    # In state diagram notes, colons after the initial "note ... :" break the parser.
+    # Strip extra colons from note body text.
+    def _fix_note_colons(m: re.Match) -> str:
+        prefix = m.group(1)  # "note right of X: "
+        body = m.group(2)
+        return prefix + body.replace(":", " -")
+
+    code = re.sub(
+        r"(note\s+(?:right|left)\s+of\s+\w+\s*:\s*)(.*)",
+        _fix_note_colons,
+        code,
+    )
+
+    return code
+
+
+def _render_mermaid_to_png(mermaid_code: str, output_dir: Path, index: int) -> Path | None:
+    """Render a mermaid diagram to PNG using mmdc.
+
+    Uses PNG (not SVG) because SVG foreignObject elements lose text
+    when converted to PDF by pandoc/typst.
+    """
+    mermaid_code = _sanitize_mermaid(mermaid_code)
+    png_path = output_dir / f"mermaid_{index:03d}.png"
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".mmd", dir=str(output_dir), delete=False
+    ) as f:
+        f.write(mermaid_code)
+        mmd_path = f.name
+
+    try:
+        result = subprocess.run(
+            ["mmdc", "-i", mmd_path, "-o", str(png_path), "-b", "white", "-s", "2"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0 or not png_path.exists():
+            logger.warning("mmdc failed for diagram %d: %s", index, result.stderr[:200])
+            return None
+        return png_path
+    except subprocess.TimeoutExpired:
+        logger.warning("mmdc timed out for diagram %d", index)
+        return None
+    finally:
+        Path(mmd_path).unlink(missing_ok=True)
+
+
+def prerender_mermaid_diagrams(content: str, work_dir: Path) -> str:
+    """Replace mermaid code blocks with rendered SVG image references.
+
+    Args:
+        content: Markdown content with mermaid blocks.
+        work_dir: Directory for temporary SVG files.
+
+    Returns:
+        Markdown with mermaid blocks replaced by image references.
+    """
+    work_dir.mkdir(parents=True, exist_ok=True)
+    counter = 0
+
+    def _replace(match: re.Match) -> str:
+        nonlocal counter
+        counter += 1
+        mermaid_code = match.group(1)
+        png_path = _render_mermaid_to_png(mermaid_code, work_dir, counter)
+        if png_path:
+            return f"![Diagram {counter}]({png_path})"
+        return f"```\n{mermaid_code}```"
+
+    result = _MERMAID_BLOCK_RE.sub(_replace, content)
+    logger.debug("Rendered %d mermaid diagrams", counter)
+    return result
+
+
+def convert_markdown_to_pdf(
+    md_path: Path,
+    output_path: Path,
+) -> Path:
+    """Convert a markdown file to PDF with pre-rendered mermaid diagrams.
+
+    Args:
+        md_path: Path to the source markdown file.
+        output_path: Path for the output PDF file.
+
+    Returns:
+        Path to the generated PDF.
+
+    Raises:
+        ConversionError: If pandoc fails or prerequisites are missing.
+    """
+    missing = check_prerequisites()
+    if missing:
+        raise ConversionError(
+            f"Missing prerequisites: {', '.join(missing)}. "
+            "Install with: brew install pandoc && npm install -g @mermaid-js/mermaid-cli"
+        )
+
+    raw_content = md_path.read_text(encoding="utf-8")
+    cleaned = preprocess_markdown(raw_content)
+
+    work_dir = output_path.parent / f".mermaid_{md_path.stem}"
+    cleaned = prerender_mermaid_diagrams(cleaned, work_dir)
+
+    temp_md = work_dir / f"{md_path.stem}_preprocessed.md"
+    try:
+        temp_md.write_text(cleaned, encoding="utf-8")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        cmd = [
+            "pandoc",
+            str(temp_md),
+            "-o",
+            str(output_path),
+            "--pdf-engine=typst",
+        ]
+
+        logger.debug("Running: %s", " ".join(cmd))
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=180)
+
+        if result.returncode != 0:
+            # Fallback to default engine (pdflatex) if typst fails
+            cmd_fallback = [
+                "pandoc",
+                str(temp_md),
+                "-o",
+                str(output_path),
+                "-V",
+                "geometry:margin=1in",
+            ]
+            result = subprocess.run(cmd_fallback, capture_output=True, text=True, timeout=180)
+            if result.returncode != 0:
+                raise ConversionError(f"pandoc failed for {md_path.name}: {result.stderr[:500]}")
+
+        if not output_path.exists():
+            raise ConversionError(f"pandoc produced no output for {md_path.name}")
+
+        logger.info("Converted %s -> %s", md_path.name, output_path.name)
+        return output_path
+
+    finally:
+        if work_dir.exists():
+            shutil.rmtree(work_dir, ignore_errors=True)
+
+
+def convert_directory(
+    source_dir: Path,
+    output_dir: Path,
+) -> list[Path]:
+    """Convert all markdown files in a directory to PDFs.
+
+    Files are sorted alphabetically and numbered sequentially.
+
+    Args:
+        source_dir: Directory containing .md files.
+        output_dir: Directory to write PDFs into.
+
+    Returns:
+        List of paths to generated PDF files, in order.
+
+    Raises:
+        ConversionError: If prerequisites are missing.
+        ValueError: If source_dir doesn't exist or has no .md files.
+    """
+    if not source_dir.is_dir():
+        raise ValueError(f"Source directory does not exist: {source_dir}")
+
+    md_files = sorted(source_dir.glob("*.md"))
+    if not md_files:
+        raise ValueError(f"No .md files found in {source_dir}")
+
+    missing = check_prerequisites()
+    if missing:
+        raise ConversionError(
+            f"Missing prerequisites: {', '.join(missing)}. "
+            "Install with: brew install pandoc && npm install -g @mermaid-js/mermaid-cli"
+        )
+
+    pdf_dir = output_dir / "pdfs"
+    pdf_dir.mkdir(parents=True, exist_ok=True)
+
+    pdfs: list[Path] = []
+    for i, md_path in enumerate(md_files, 1):
+        stem = re.sub(r"-{2,}", "-", md_path.stem.lower().replace(" ", "_"))
+        pdf_name = f"{i:02d}-{stem}.pdf"
+        pdf_path = pdf_dir / pdf_name
+
+        try:
+            convert_markdown_to_pdf(md_path, pdf_path)
+            pdfs.append(pdf_path)
+        except ConversionError as exc:
+            logger.error("Failed to convert %s: %s", md_path.name, exc)
+
+    logger.info("Converted %d/%d files to %s", len(pdfs), len(md_files), pdf_dir)
+    return pdfs

studyctl/content/models.py

@@ -0,0 +1,31 @@
+"""Shared data models for the content pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class UploadResult:
+    """Result of uploading chapters to a notebook."""
+
+    id: str
+    title: str
+    chapters: int
+
+
+@dataclass
+class NotebookInfo:
+    """Summary of a NotebookLM notebook."""
+
+    id: str
+    title: str
+    sources_count: int
+
+
+@dataclass
+class SourceInfo:
+    """Summary of a source within a notebook."""
+
+    id: str
+    title: str