studyctl 2.0.0__py3-none-any.whl

studyctl/cli/_setup.py

@@ -0,0 +1,164 @@
+"""Setup wizard — first-run configuration for studyctl.
+
+Guides users through the essential configuration questions one at a time.
+Designed to be AuDHD-friendly: clear steps, no overwhelming walls of text,
+sensible defaults so pressing Enter always works.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import subprocess
+from pathlib import Path
+
+import click
+import yaml
+
+from studyctl.cli._shared import console
+from studyctl.settings import CONFIG_DIR
+
+
+def _validate_path(value: str) -> Path:
+    """Expand user and return a Path; raise UsageError if obviously invalid."""
+    p = Path(value).expanduser()
+    return p
+
+
+@click.command(name="setup")
+def setup() -> None:
+    """First-run setup wizard — configure studyctl in under 2 minutes."""
+
+    # ------------------------------------------------------------------
+    # Banner
+    # ------------------------------------------------------------------
+    console.print()
+    console.print("[bold cyan]studyctl setup[/bold cyan]")
+    console.print(
+        "studyctl is your AuDHD study pipeline: it syncs Obsidian notes to "
+        "NotebookLM, tracks spaced-repetition reviews, and schedules focused "
+        "study sessions.\n"
+    )
+    console.print("[dim]Press Enter to accept the default shown in brackets.[/dim]\n")
+
+    config: dict = {}
+
+    # ------------------------------------------------------------------
+    # Step 1 — Study materials directory
+    # ------------------------------------------------------------------
+    console.print("[bold]Step 1 of 5[/bold]  Where do you store course materials (PDFs, slides)?")
+    materials_raw = click.prompt(
+        "Study materials path",
+        default="~/study-materials",
+    )
+    materials_path = _validate_path(materials_raw)
+    config["content"] = {"base_path": str(materials_raw)}
+    console.print(f"  [dim]Will use: {materials_path}[/dim]\n")
+
+    # ------------------------------------------------------------------
+    # Step 2 — AI coding assistant / MCP registration
+    # ------------------------------------------------------------------
+    console.print("[bold]Step 2 of 5[/bold]  Do you use an AI coding assistant?")
+    console.print("  [dim](Claude Code, Kiro, Gemini CLI, etc.)[/dim]")
+    has_ai = click.confirm("  Use an AI assistant?", default=True)
+    if has_ai:
+        assistant = click.prompt(
+            "  Which one",
+            default="claude-code",
+            type=click.Choice(
+                ["claude-code", "kiro", "gemini-cli", "other"],
+                case_sensitive=False,
+            ),
+            show_choices=True,
+        )
+        config["ai_assistant"] = assistant
+        console.print(
+            f"  [dim]Noted. Run 'studyctl config init' to install agent definitions "
+            f"for {assistant}.[/dim]\n"
+        )
+    else:
+        console.print("  [dim]No problem — studyctl works fine as a standalone CLI.[/dim]\n")
+
+    # ------------------------------------------------------------------
+    # Step 3 — NotebookLM
+    # ------------------------------------------------------------------
+    console.print("[bold]Step 3 of 5[/bold]  Do you use Google NotebookLM?")
+    console.print("  [dim](Optional — enables audio overview generation from your notes)[/dim]")
+    use_nlm = click.confirm("  Enable NotebookLM integration?", default=False)
+    config["notebooklm"] = {"enabled": use_nlm}
+    if use_nlm:
+        console.print(
+            "  [dim]NotebookLM enabled. You'll need a Google account"
+            " with NotebookLM access.[/dim]\n"
+        )
+    else:
+        console.print("  [dim]Skipped — you can enable this later in config.yaml.[/dim]\n")
+
+    # ------------------------------------------------------------------
+    # Step 4 — Obsidian vault
+    # ------------------------------------------------------------------
+    console.print("[bold]Step 4 of 5[/bold]  Where is your Obsidian vault?")
+    console.print("  [dim](Optional — enables note sync and spaced repetition)[/dim]")
+    use_obsidian = click.confirm("  Configure Obsidian integration?", default=True)
+    if use_obsidian:
+        obsidian_raw = click.prompt("  Obsidian vault path", default="~/Obsidian")
+        obsidian_path = _validate_path(obsidian_raw)
+        config["obsidian_base"] = str(obsidian_raw)
+        if not obsidian_path.exists():
+            console.print(
+                f"  [yellow]Note: {obsidian_path} does not exist yet. "
+                f"Create it before running sync.[/yellow]\n"
+            )
+        else:
+            console.print(f"  [green]Found vault at {obsidian_path}[/green]\n")
+    else:
+        console.print("  [dim]Skipped — you can set obsidian_base in config.yaml later.[/dim]\n")
+
+    # ------------------------------------------------------------------
+    # Step 5 — Write config
+    # ------------------------------------------------------------------
+    console.print("[bold]Step 5 of 5[/bold]  Writing configuration...")
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    config_path = CONFIG_DIR / "config.yaml"
+
+    # Preserve any existing keys by loading first, then merging
+    existing: dict = {}
+    if config_path.exists():
+        with contextlib.suppress(yaml.YAMLError):
+            existing = yaml.safe_load(config_path.read_text()) or {}
+
+    # New values take precedence over existing
+    merged = {**existing, **config}
+    # Nested dicts: merge content and notebooklm sub-keys
+    for key in ("content", "notebooklm"):
+        if key in existing and key in config and isinstance(existing[key], dict):
+            merged[key] = {**existing[key], **config[key]}
+
+    config_path.write_text(yaml.dump(merged, default_flow_style=False, sort_keys=False))
+
+    console.print(f"\n[bold green]Configuration saved to {config_path}[/bold green]")
+
+    # ------------------------------------------------------------------
+    # Offer to launch web UI
+    # ------------------------------------------------------------------
+    console.print()
+    launch = click.confirm("Launch the studyctl web UI now?", default=False)
+    if launch:
+        console.print("[dim]Starting web UI on http://localhost:8000 ...[/dim]")
+        try:
+            subprocess.Popen(
+                ["studyctl", "web"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            console.print(
+                "[green]Web UI started. Open http://localhost:8000 in your browser.[/green]"
+            )
+        except FileNotFoundError:
+            console.print("[yellow]Could not launch web UI. Run 'studyctl web' manually.[/yellow]")
+    else:
+        console.print("\n[bold]You're all set.[/bold] Next steps:")
+        console.print("  studyctl config show    — review your configuration")
+        console.print("  studyctl review         — see what topics are due for review")
+        console.print("  studyctl web            — open the web UI")
+        console.print("  studyctl --help         — explore all commands")

studyctl/cli/_shared.py

@@ -0,0 +1,83 @@
+"""Shared CLI utilities — console, helpers, constants."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from rich.console import Console
+
+from studyctl.settings import Topic, get_topics
+
+console = Console()
+
+# Topic keywords for session DB queries
+TOPIC_KEYWORDS = {
+    "python": [
+        "python",
+        "pattern",
+        "dataclass",
+        "protocol",
+        "abc",
+        "strategy",
+        "bridge",
+        "decorator",
+    ],
+    "sql": ["sql", "query", "join", "index", "postgresql", "athena", "redshift", "window function"],
+    "data-engineering": [
+        "spark",
+        "glue",
+        "pipeline",
+        "etl",
+        "airflow",
+        "dbt",
+        "kafka",
+        "partition",
+        "dag",
+    ],
+    "aws-analytics": ["sagemaker", "athena", "redshift", "lake formation", "emr", "glue catalog"],
+}
+
+
+def get_topic(name: str) -> Topic | None:
+    """Find a topic by name (exact or substring match)."""
+    for t in get_topics():
+        if t.name == name or name in t.name:
+            return t
+    return None
+
+
+def offer_agent_install(flag: bool | None) -> None:
+    """Offer to install AI agent definitions after config init.
+
+    Args:
+        flag: True = install, False = skip, None = ask interactively.
+    """
+    # Find install-agents.sh relative to the package
+    candidate = Path(__file__).resolve().parent.parent
+    for _ in range(6):
+        script = candidate / "scripts" / "install-agents.sh"
+        if script.exists():
+            break
+        candidate = candidate.parent
+    else:
+        return  # Script not found — skip silently (pip install, not git clone)
+
+    if flag is None:
+        console.print("\n[bold cyan]Agent Installation[/bold cyan]")
+        console.print(
+            "The study mentor agents can be installed for detected AI tools\n"
+            "(Claude Code, Kiro CLI, Gemini, OpenCode, Amp).\n"
+        )
+        reply = input("Install agent definitions now? [Y/n] ").strip().lower()
+        flag = reply in ("", "y", "yes")
+
+    if flag:
+        console.print("[dim]Running install-agents.sh...[/dim]")
+        result = subprocess.run(["bash", str(script)], capture_output=True, text=True)
+        if result.returncode == 0:
+            for line in result.stdout.strip().splitlines():
+                console.print(f"  {line}")
+        else:
+            console.print("[yellow]Agent install had issues — run manually:[/yellow]")
+            console.print(f"  bash {script}")

studyctl/cli/_state.py

@@ -0,0 +1,69 @@
+"""State commands — cross-machine state sync."""
+
+from __future__ import annotations
+
+import click
+
+from studyctl.cli._shared import console
+from studyctl.shared import init_config, pull_state, push_state
+from studyctl.shared import sync_status as shared_sync_status
+
+
+@click.group(name="state")
+def state_group() -> None:
+    """Cross-machine state sync (via Obsidian vault)."""
+
+
+@state_group.command(name="push")
+@click.argument("remote", required=False)
+def state_push(remote: str | None) -> None:
+    """Push local progress and sync state to remote machine(s)."""
+    try:
+        pushed = push_state(remote)
+    except FileNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        console.print("Run 'studyctl state init' first")
+        raise SystemExit(1) from None
+    if pushed:
+        for f in pushed:
+            console.print(f"[green]\u2713[/green] {f}")
+    else:
+        console.print("[dim]Everything up to date (or no remotes reachable)[/dim]")
+
+
+@state_group.command(name="pull")
+@click.argument("remote", required=False)
+def state_pull(remote: str | None) -> None:
+    """Pull progress and sync state from remote machine(s)."""
+    try:
+        pulled = pull_state(remote)
+    except FileNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1) from None
+    if pulled:
+        for f in pulled:
+            console.print(f"[green]\u2713[/green] {f}")
+    else:
+        console.print("[dim]Everything up to date (or no remotes reachable)[/dim]")
+
+
+@state_group.command(name="status")
+def state_status_cmd() -> None:
+    """Check sync config and remote connectivity."""
+    info = shared_sync_status()
+    if not info["configured"]:
+        console.print("[red]Not configured.[/red] Run: studyctl state init")
+        console.print(f"Config: {info['config_path']}")
+        return
+    console.print(f"Local machine: [bold]{info['local']}[/bold]")
+    for name, r in info["remotes"].items():
+        status = "[green]reachable[/green]" if r["reachable"] else "[red]unreachable[/red]"
+        console.print(f"  {name} ({r['host']}): {status}")
+
+
+@state_group.command(name="init")
+def state_init() -> None:
+    """Create default sync config."""
+    path = init_config()
+    console.print(f"[green]\u2713[/green] Config at {path}")
+    console.print("Edit remotes to match your machines, then run 'studyctl state status'")

studyctl/cli/_sync.py

@@ -0,0 +1,156 @@
+"""Sync commands — Obsidian to NotebookLM sync, audio generation."""
+
+from __future__ import annotations
+
+import click
+from rich.table import Table
+
+from studyctl.cli._shared import console, get_topic
+from studyctl.maintenance import dedup_notebook, find_duplicates
+from studyctl.settings import get_topics
+from studyctl.state import SyncState
+from studyctl.sync import find_changed_sources, find_sources, generate_audio, sync_topic
+
+
+@click.command()
+@click.argument("topic_name", required=False)
+@click.option("--all", "sync_all", is_flag=True, help="Sync all topics")
+@click.option("--dry-run", is_flag=True, help="Show what would be synced")
+def sync(topic_name: str | None, sync_all: bool, dry_run: bool) -> None:
+    """Sync Obsidian course notes to NotebookLM notebooks."""
+    state = SyncState()
+    topics = get_topics() if sync_all else ([get_topic(topic_name)] if topic_name else [])
+    topics = [t for t in topics if t]
+
+    if not topics:
+        console.print("[red]Specify a topic name or use --all[/red]")
+        console.print("Topics: " + ", ".join(t.name for t in get_topics()))
+        raise SystemExit(1)
+
+    for topic in topics:
+        result = sync_topic(topic, state, dry_run=dry_run)
+        prefix = "[dim]DRY RUN[/dim] " if dry_run else ""
+        nb = topic.notebook_id[:8] + "..." if topic.notebook_id else "[yellow]new[/yellow]"
+        if result["changed"] == 0:
+            console.print(f"{prefix}[dim]{topic.display_name} ({nb}): up to date[/dim]")
+        else:
+            changed = result["changed"]
+            total = result["total"]
+            synced = result["synced"]
+            failed = result["failed"]
+            console.print(
+                f"{prefix}[bold]{topic.display_name}[/bold] → {nb}: "
+                f"{changed}/{total} to sync, {synced} done, {failed} failed"
+            )
+            if dry_run and result.get("files"):
+                for f in result["files"]:
+                    console.print(f"  [dim]  {f}[/dim]")
+                if result["changed"] > 10:
+                    console.print(f"  [dim]  ... and {result['changed'] - 10} more[/dim]")
+
+
+@click.command()
+@click.argument("topic_name", required=False)
+def status(topic_name: str | None) -> None:
+    """Show sync status for topics."""
+    state = SyncState()
+    topics = [get_topic(topic_name)] if topic_name else get_topics()
+    topics = [t for t in topics if t]
+
+    table = Table(title="Study Pipeline Status")
+    table.add_column("Topic", style="bold cyan")
+    table.add_column("Notebook", style="dim")
+    table.add_column("Sources", justify="right")
+    table.add_column("Changed", justify="right")
+    table.add_column("Last Sync", style="dim")
+
+    for topic in topics:
+        ts = state.get_topic(topic.name)
+        total = len(find_sources(topic))
+        changed = len(find_changed_sources(topic, state))
+        nb = ts.notebook_id[:8] + "..." if ts.notebook_id else "[red]not created[/red]"
+        synced_count = len(ts.sources)
+        last = ts.last_sync[:10] if ts.last_sync else "never"
+        table.add_row(
+            topic.display_name,
+            nb,
+            f"{synced_count}/{total}",
+            str(changed) if changed else "[green]0[/green]",
+            last,
+        )
+
+    console.print(table)
+
+
+@click.command()
+@click.argument("topic_name")
+@click.option("--instructions", "-i", default="", help="Custom instructions for audio generation")
+def audio(topic_name: str, instructions: str) -> None:
+    """Generate a NotebookLM audio overview for a topic."""
+    topic = get_topic(topic_name)
+    if not topic:
+        console.print(f"[red]Unknown topic: {topic_name}[/red]")
+        raise SystemExit(1)
+
+    state = SyncState()
+    ts = state.get_topic(topic.name)
+    if not ts.notebook_id:
+        console.print("[red]Notebook not created yet. Run 'studyctl sync' first.[/red]")
+        raise SystemExit(1)
+
+    console.print(f"Generating audio for [bold]{topic.display_name}[/bold]...")
+    task_id = generate_audio(topic, state, instructions)
+    if task_id:
+        console.print(f"[green]\u2713[/green] Audio generation started (task: {task_id})")
+        console.print(f"  Check status: notebooklm artifact list --notebook {ts.notebook_id}")
+    else:
+        console.print("[red]Failed to start audio generation[/red]")
+
+
+@click.command()
+def topics() -> None:
+    """List configured study topics."""
+    for topic in get_topics():
+        console.print(f"[bold cyan]{topic.name}[/bold cyan] \u2014 {topic.display_name}")
+        for p in topic.obsidian_paths:
+            exists = "\u2713" if p.exists() else "\u2717"
+            console.print(f"  {exists} {p}")
+
+
+@click.command()
+@click.argument("topic_name", required=False)
+@click.option("--all", "dedup_all", is_flag=True, help="Dedup all topic notebooks")
+@click.option("--dry-run", is_flag=True, help="Show duplicates without removing")
+def dedup(topic_name: str | None, dedup_all: bool, dry_run: bool) -> None:
+    """Remove duplicate sources from NotebookLM notebooks."""
+    state = SyncState()
+    topics = get_topics() if dedup_all else ([get_topic(topic_name)] if topic_name else [])
+    topics = [t for t in topics if t]
+
+    if not topics:
+        console.print("[red]Specify a topic or use --all[/red]")
+        raise SystemExit(1)
+
+    for topic in topics:
+        ts = state.get_topic(topic.name)
+        if not ts.notebook_id:
+            console.print(f"[dim]{topic.display_name}: no notebook[/dim]")
+            continue
+
+        dupes = find_duplicates(ts.notebook_id)
+        if not dupes:
+            console.print(f"[dim]{topic.display_name}: no duplicates[/dim]")
+            continue
+
+        total_dupes = sum(len(v) - 1 for v in dupes.values())
+        name = topic.display_name
+        console.print(f"[bold]{name}[/bold]: {total_dupes} duplicates across {len(dupes)} titles")
+        for title, sources in dupes.items():
+            console.print(
+                f"  {len(sources)}x {title}"
+                + (" [dim](keeping newest)[/dim]" if not dry_run else "")
+            )
+
+        if not dry_run:
+            result = dedup_notebook(ts.notebook_id)
+            console.print(f"  [green]\u2713[/green] Removed {result['removed']} duplicates")