studyctl 2.4.0__tar.gz → 2.5.0__tar.gz

{studyctl-2.4.0 → studyctl-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: studyctl
-Version: 2.4.0
+Version: 2.5.0
 Summary: AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline
 Project-URL: Homepage, https://github.com/NetDevAutomate/socratic-study-mentor
 Project-URL: Repository, https://github.com/NetDevAutomate/socratic-study-mentor

{studyctl-2.4.0 → studyctl-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "studyctl"
-version = "2.4.0"
+version = "2.5.0"
 description = "AuDHD-aware study tool with AI Socratic mentoring, spaced repetition, and content pipeline"
 requires-python = ">=3.12"
 readme = "README.md"

studyctl-2.5.0/src/studyctl/adapters/codex.py

@@ -0,0 +1,39 @@
+"""Codex adapter — persona via AGENTS.md in session CWD.
+
+Codex CLI auto-loads AGENTS.md from the current working directory.
+The setup function writes the canonical persona as plain markdown in
+the session directory; launch just invokes the codex binary there.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from studyctl.adapters._protocol import AgentAdapter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _codex_setup(canonical_content: str, session_dir: Path) -> Path:
+    """Write AGENTS.md to the session dir for Codex auto-discovery."""
+    persona_path = session_dir / "AGENTS.md"
+    persona_path.write_text(canonical_content)
+    return persona_path
+
+
+def _codex_launch(_persona_path: Path, resume: bool) -> str:
+    """Build Codex launch command. Codex reads AGENTS.md from cwd."""
+    binary = shutil.which("codex") or "codex"
+    if resume:
+        return f"{binary} --resume"
+    return binary
+
+
+ADAPTER = AgentAdapter(
+    name="codex",
+    binary="codex",
+    setup=_codex_setup,
+    launch_cmd=_codex_launch,
+)

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/agent_launcher.py

@@ -24,6 +24,7 @@ from studyctl.adapters._local_llm import _get_local_llm_config, _local_llm_env_p
 from studyctl.adapters._protocol import AgentAdapter
 from studyctl.adapters._strategies import cli_flag_setup as _claude_setup
 from studyctl.adapters.claude import _claude_launch
+from studyctl.adapters.codex import _codex_launch, _codex_setup
 from studyctl.adapters.gemini import _gemini_launch, _gemini_setup
 from studyctl.adapters.kiro import _KIRO_BACKUP_SUFFIX, KIRO_AGENT_NAME
 from studyctl.adapters.lmstudio import _lmstudio_launch
@@ -42,6 +43,8 @@ __all__ = [
     "AgentAdapter",
     "_claude_launch",
     "_claude_setup",
+    "_codex_launch",
+    "_codex_setup",
     "_gemini_launch",
     "_gemini_mcp",
     "_gemini_setup",

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/__init__.py

@@ -22,6 +22,8 @@ from studyctl.cli._lazy import LazyGroup
         "dedup": "studyctl.cli._sync:dedup",
         # _setup.py — first-run setup wizard
         "setup": "studyctl.cli._setup:setup",
+        # _install.py — typed installation helpers
+        "install": "studyctl.cli._install:install_group",
         # _config.py — configuration
         "config": "studyctl.cli._config:config_group",
         # _review.py — spaced repetition, progress, wins, streaks, bridges

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_doctor.py

@@ -9,6 +9,15 @@ from rich.table import Table
 
 from studyctl.cli._shared import console
 from studyctl.doctor.models import VALID_CATEGORIES, CheckResult
+from studyctl.installers import (
+    InstallError,
+    ensure_default_config,
+    ensure_review_database,
+    ensure_review_directories,
+    install_agent_definitions,
+    install_workspace_tools,
+    require_repo_root,
+)
 
 
 def _get_registry():
@@ -94,13 +103,70 @@ def _summary_line(results: list[CheckResult]) -> str:
         parts.append(f"{counts['info']} info")
     summary = ", ".join(parts) + "."
     if auto_fixable:
-        summary += f" Run 'studyctl upgrade' to fix {auto_fixable} issues."
+        summary += f" Run 'studyctl doctor --fix' to fix {auto_fixable} issues."
     return summary
 
 
+def _apply_fixes(results: list[CheckResult]) -> list[str]:
+    """Apply safe automatic fixes for the provided results."""
+    actions: list[str] = []
+
+    def needs(category: str, name: str | None = None) -> bool:
+        return any(
+            r.category == category
+            and (name is None or r.name == name)
+            and r.status in ("warn", "fail")
+            and r.fix_auto
+            for r in results
+        )
+
+    if needs("core", "config_file"):
+        path = ensure_default_config()
+        actions.append(f"created config: {path}")
+
+    if needs("core", "agent_session_tools"):
+        repo_root = require_repo_root()
+        install_workspace_tools(repo_root, sync_workspace=True, force=True)
+        actions.append("reinstalled workspace tools")
+
+    if any(
+        r.category == "config"
+        and r.name.startswith("review_dir_")
+        and r.status in ("warn", "fail")
+        and r.fix_auto
+        for r in results
+    ):
+        created = ensure_review_directories()
+        actions.append(f"ensured review directories ({len(created)} created)")
+
+    if needs("database", "review_db"):
+        db_path = ensure_review_database()
+        actions.append(f"migrated review DB: {db_path}")
+
+    if any(r.category == "agents" and r.status in ("warn", "fail") and r.fix_auto for r in results):
+        repo_root = require_repo_root()
+        summary = install_agent_definitions(repo_root)
+        changed = sum(summary.values())
+        actions.append(f"refreshed agent definitions ({changed} changes)")
+
+    if any(
+        r.category == "updates" and r.status in ("warn", "fail") and r.fix_auto for r in results
+    ):
+        from studyctl.cli._upgrade import _detect_package_manager, _upgrade_packages
+
+        manager = _detect_package_manager()
+        if not _upgrade_packages(manager, dry_run=False):
+            msg = "package upgrade failed"
+            raise InstallError(msg)
+        actions.append(f"upgraded packages via {manager}")
+
+    return actions
+
+
 @click.command("doctor")
 @click.option("--json", "as_json", is_flag=True, help="Output as JSON array")
 @click.option("--quiet", is_flag=True, help="Summary line only")
+@click.option("--fix", is_flag=True, help="Apply safe automatic fixes before reporting.")
 @click.option(
     "--category",
     type=click.Choice(sorted(VALID_CATEGORIES)),
@@ -108,11 +174,25 @@ def _summary_line(results: list[CheckResult]) -> str:
     help="Check specific category",
 )
 @click.pass_context
-def doctor(ctx: click.Context, as_json: bool, quiet: bool, category: str | None) -> None:
+def doctor(
+    ctx: click.Context,
+    as_json: bool,
+    quiet: bool,
+    fix: bool,
+    category: str | None,
+) -> None:
     """Check installation health and report issues."""
     registry = _get_registry()
 
     results = registry.run_category(category) if category else registry.run_all()
+    applied: list[str] = []
+    if fix:
+        try:
+            applied = _apply_fixes(results)
+        except (InstallError, click.ClickException) as exc:
+            raise click.ClickException(str(exc)) from exc
+        if applied:
+            results = registry.run_category(category) if category else registry.run_all()
 
     exit_code = _compute_exit_code(results)
 
@@ -127,6 +207,12 @@ def doctor(ctx: click.Context, as_json: bool, quiet: bool, category: str | None)
         return
 
     # Rich table output grouped by category
+    if applied:
+        console.print("[bold green]Applied fixes:[/bold green]")
+        for action in applied:
+            console.print(f"  {action}")
+        console.print()
+
     table = Table(title="studyctl doctor", show_lines=False)
     table.add_column("Status", justify="center", width=3)
     table.add_column("Check", style="cyan")

studyctl-2.5.0/src/studyctl/cli/_install.py

@@ -0,0 +1,80 @@
+"""Typed install commands for tools and agent definitions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from studyctl.cli._shared import console
+from studyctl.installers import (
+    InstallError,
+    install_agent_definitions,
+    install_workspace_tools,
+    require_repo_root,
+)
+
+
+@click.group(name="install")
+def install_group() -> None:
+    """Install studyctl tools and agent definitions."""
+
+
+@install_group.command(name="tools")
+@click.option(
+    "--repo-root",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    default=None,
+    help="Repository root to install from (defaults to auto-detect).",
+)
+@click.option("--sync/--skip-sync", default=True, show_default=True, help="Run `uv sync` first.")
+@click.option(
+    "--force/--no-force",
+    default=True,
+    show_default=True,
+    help="Force reinstall uv tools.",
+)
+def install_tools(repo_root: Path | None, sync: bool, force: bool) -> None:
+    """Install editable workspace packages as uv tools."""
+    try:
+        root = require_repo_root(repo_root)
+        installed = install_workspace_tools(root, sync_workspace=sync, force=force)
+    except InstallError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except Exception as exc:
+        raise click.ClickException(f"Tool installation failed: {exc}") from exc
+
+    console.print("[green]Installed tools:[/green] " + ", ".join(installed))
+
+
+@install_group.command(name="agents")
+@click.option(
+    "--repo-root",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    default=None,
+    help="Repository root to install from (defaults to auto-detect).",
+)
+@click.option(
+    "--tool",
+    "tools",
+    multiple=True,
+    type=click.Choice(["kiro", "claude", "gemini", "opencode", "codex", "amp"]),
+    help="Install for a specific AI tool. Repeat to install multiple.",
+)
+@click.option("--uninstall", is_flag=True, help="Remove installed agent definitions instead.")
+def install_agents(repo_root: Path | None, tools: tuple[str, ...], uninstall: bool) -> None:
+    """Install or remove agent definitions for supported AI tools."""
+    try:
+        root = require_repo_root(repo_root)
+        summary = install_agent_definitions(root, tools=list(tools) or None, uninstall=uninstall)
+    except InstallError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except Exception as exc:
+        action = "Agent uninstall" if uninstall else "Agent install"
+        raise click.ClickException(f"{action} failed: {exc}") from exc
+
+    action_word = "Removed" if uninstall else "Updated"
+    lines = [f"{name}: {count}" for name, count in summary.items()]
+    console.print(f"[green]{action_word} agent definitions.[/green]")
+    for line in lines:
+        console.print(f"  {line}")

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_session.py

@@ -29,9 +29,18 @@ def session_start(topic: str, energy: int) -> None:
         PARKING_FILE,
         TOPICS_FILE,
         _ensure_session_dir,
+        is_session_active,
         write_session_state,
     )
 
+    if is_session_active():
+        console.print(
+            "[yellow]A session is already active.[/yellow]\n"
+            "  Check:  [bold]studyctl session status[/bold]\n"
+            "  End:    [bold]studyctl session end[/bold]"
+        )
+        raise SystemExit(1)
+
     _ensure_session_dir()
 
     from studyctl.output import energy_to_label

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_setup.py

@@ -58,14 +58,14 @@ def setup() -> None:
     # 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]")
+    console.print("  [dim](Claude Code, Codex CLI, 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"],
+                ["claude-code", "codex", "kiro", "gemini-cli", "other"],
                 case_sensitive=False,
             ),
             show_choices=True,

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_shared.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
-import subprocess
 from pathlib import Path
 
+from click import ClickException
+
+from studyctl.installers import InstallError, install_agent_definitions, require_repo_root
 from studyctl.output import console
 from studyctl.topics import Topic, get_topics
 
@@ -50,31 +52,26 @@ def offer_agent_install(flag: bool | None) -> None:
     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"
+            "(Claude Code, Codex CLI, 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}")
+        try:
+            repo_root = require_repo_root(Path.cwd())
+            summary = install_agent_definitions(repo_root)
+        except (InstallError, OSError) as exc:
+            console.print(f"[yellow]Agent install skipped:[/yellow] {exc}")
+            return
+        except ClickException as exc:
+            console.print(f"[yellow]Agent install skipped:[/yellow] {exc}")
+            return
+
+        console.print("[green]Agent definitions installed.[/green]")
+        for name, count in summary.items():
+            console.print(f"  {name}: {count}")

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_study.py

@@ -242,7 +242,7 @@ def sidebar_cmd() -> None:
     except ImportError:
         console.print(
             "[red]Textual is required for the sidebar.[/red]\n"
-            "  Install: [bold]pip install 'studyctl[tui]'[/bold]"
+            "  Install: pip install 'studyctl[tui]'"
         )
         raise SystemExit(1) from None
 

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/cli/_upgrade.py

@@ -15,6 +15,7 @@ from rich.table import Table
 
 from studyctl.cli._doctor import _get_registry
 from studyctl.cli._shared import console
+from studyctl.installers import InstallError, install_agent_definitions, require_repo_root
 
 if TYPE_CHECKING:
     from studyctl.doctor.models import CheckResult
@@ -171,6 +172,28 @@ def _upgrade_database(dry_run: bool) -> bool:
     return True
 
 
+def _upgrade_agents(dry_run: bool) -> bool:
+    """Install or refresh agent definitions from the current source checkout."""
+    try:
+        repo_root = require_repo_root()
+    except InstallError as exc:
+        console.print(f"[red]  Agent upgrade failed:[/red] {exc}")
+        return False
+
+    if dry_run:
+        console.print(f"  [dim]Would refresh agent definitions from {repo_root}[/dim]")
+        return True
+
+    try:
+        install_agent_definitions(repo_root)
+    except Exception as exc:
+        console.print(f"[red]  Agent upgrade failed:[/red] {exc}")
+        return False
+
+    console.print("[green]  Agent definitions refreshed.[/green]")
+    return True
+
+
 def _result_matches_component(result: CheckResult, component: str) -> bool:
     """Return True if *result* is relevant to the upgrade *component*."""
     if component == "all":
@@ -263,12 +286,15 @@ def upgrade(ctx: click.Context, dry_run: bool, component: str, force: bool) -> N
                 _upgrade_packages(manager, dry_run=True)
             elif mapped == "database":
                 _upgrade_database(dry_run=True)
+            elif mapped == "agents":
+                _upgrade_agents(dry_run=True)
         ctx.exit(0)
         return
 
     # Non-dry-run: apply upgrades grouped by component
     needs_packages = any(_CATEGORY_TO_COMPONENT.get(r.category) == "packages" for r in actionable)
     needs_database = any(_CATEGORY_TO_COMPONENT.get(r.category) == "database" for r in actionable)
+    needs_agents = any(_CATEGORY_TO_COMPONENT.get(r.category) == "agents" for r in actionable)
 
     success = True
 
@@ -283,6 +309,11 @@ def upgrade(ctx: click.Context, dry_run: bool, component: str, force: bool) -> N
         if not _upgrade_database(dry_run=False):
             success = False
 
+    if needs_agents:
+        console.print("[bold]Upgrading agent definitions...[/bold]")
+        if not _upgrade_agents(dry_run=False):
+            success = False
+
     if success:
         console.print("\n[green]Upgrade complete.[/green]")
     else:

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/doctor/agents.py

@@ -16,11 +16,13 @@ import urllib.request
 from pathlib import Path
 
 from studyctl.doctor.models import CheckResult
+from studyctl.installers import find_repo_root
 
 MANIFEST_URL = "https://raw.githubusercontent.com/NetDevAutomate/socratic-study-mentor/main/agents/manifest.json"
 
 TOOL_AGENTS: dict[str, tuple[str, str]] = {
     "claude": ("claude", "~/.claude/commands/socratic-mentor.md"),
+    "codex": ("codex", "{repo_root}/AGENTS.md"),
     "kiro": ("kiro-cli", "~/.kiro/agents/study-mentor.json"),
     "gemini": ("gemini", "~/.gemini/agents/study-mentor.md"),
     "opencode": ("opencode", "~/.config/opencode/agents/study-mentor.md"),
@@ -35,6 +37,9 @@ def _detect_ai_tools() -> list[str]:
 
 def _get_agent_install_path(tool: str) -> Path:
     _, path_template = TOOL_AGENTS[tool]
+    if "{repo_root}" in path_template:
+        repo_root = find_repo_root(Path.cwd()) or Path.cwd()
+        return Path(path_template.format(repo_root=repo_root)).expanduser()
     return Path(path_template).expanduser()
 
 
@@ -230,7 +235,7 @@ def check_agent_definitions() -> list[CheckResult]:
                 "no_ai_tools",
                 "info",
                 "No AI coding tools detected",
-                "Install Claude Code, Kiro CLI, Gemini CLI, or OpenCode",
+                "Install Claude Code, Codex CLI, Kiro CLI, Gemini CLI, OpenCode, or Amp",
                 False,
             )
         ]

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/doctor/core.py

@@ -68,7 +68,7 @@ def check_agent_session_tools() -> list[CheckResult]:
                 "agent_session_tools",
                 "warn",
                 "agent-session-tools not installed (sessions DB unavailable)",
-                "uv pip install agent-session-tools",
+                "studyctl install tools",
                 fix_auto=True,
             )
         ]
@@ -101,7 +101,7 @@ def check_config_file() -> list[CheckResult]:
                 "config_file",
                 "warn",
                 f"Config not found: {config_path}",
-                "studyctl config init",
+                "studyctl doctor --fix",
                 fix_auto=True,
             )
         ]

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/history/__init__.py

@@ -18,6 +18,7 @@ from .progress import (
 )
 from .search import struggle_topics, topic_frequency
 from .sessions import (
+    abort_study_session,
     end_study_session,
     get_energy_session_data,
     get_last_session_summary,
@@ -30,6 +31,7 @@ from .teachback import get_teachback_history, record_teachback
 
 __all__ = [
     "ConceptSummary",
+    "abort_study_session",
     "check_medication_window",
     "end_study_session",
     "get_bridges",

studyctl-2.5.0/src/studyctl/history/_connection.py

@@ -0,0 +1,69 @@
+"""Shared database connection helpers for the history package.
+
+Auto-creates the sessions DB and applies migrations on first use,
+so ``studyctl study`` works on a fresh machine without ``studyctl doctor``
+or any other bootstrap step.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..db import connect_db
+from ..settings import load_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _get_db_path():
+    """Return the configured sessions DB path (always a Path, never None)."""
+    return load_settings().session_db
+
+
+def _has_schema(conn) -> bool:
+    """Check whether the study_sessions table exists."""
+    row = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='study_sessions'"
+    ).fetchone()
+    return row is not None
+
+
+def _connect():
+    """Open a connection to sessions.db, applying schema and migrations.
+
+    On every connection: applies base schema if tables are missing, then
+    runs any pending migrations.  Both operations are idempotent.
+    Returns ``None`` only if agent-session-tools is not installed or
+    schema setup fails.
+    """
+    db = _get_db_path()
+    db.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = connect_db(db, row_factory=True)
+
+    try:
+        from agent_session_tools.export_sessions import SCHEMA_FILE
+        from agent_session_tools.migrations import migrate
+    except ImportError:
+        # Without agent-session-tools we can still read an existing DB
+        # but cannot create or upgrade one.
+        if _has_schema(conn):
+            return conn
+        logger.warning("agent-session-tools not installed — cannot initialise sessions DB")
+        conn.close()
+        return None
+
+    try:
+        if not _has_schema(conn):
+            with open(SCHEMA_FILE) as f:
+                conn.executescript(f.read())
+            logger.info("Created sessions DB at %s", db)
+
+        # Always run pending migrations — safe on an up-to-date DB
+        migrate(conn)
+    except Exception:
+        logger.exception("Failed to initialise/migrate sessions DB")
+        conn.close()
+        return None
+
+    return conn

{studyctl-2.4.0 → studyctl-2.5.0}/src/studyctl/history/sessions.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import logging
 import sqlite3
 import uuid
 from datetime import UTC, datetime
 
 from . import _connection, search
 
+logger = logging.getLogger(__name__)
+
 
 def start_study_session(
     topic: str,
@@ -34,6 +37,10 @@ def start_study_session(
         conn.commit()
         return study_id
     except sqlite3.OperationalError:
+        logger.warning(
+            "Failed to insert study session — sessions DB may lack schema",
+            exc_info=True,
+        )
         return None
     finally:
         conn.close()
@@ -108,6 +115,34 @@ def end_study_session(
         conn.close()
 
 
+def abort_study_session(study_id: str, reason: str) -> bool:
+    """Mark a study session as ended when startup fails before steady state."""
+    conn = _connection._connect()
+    if not conn:
+        return False
+    try:
+        now = datetime.now(UTC).isoformat()
+        conn.execute(
+            """
+            UPDATE study_sessions
+            SET ended_at = COALESCE(ended_at, ?),
+                duration_minutes = COALESCE(duration_minutes, 0),
+                notes = CASE
+                    WHEN notes IS NULL OR notes = '' THEN ?
+                    ELSE notes || char(10) || ?
+                END
+            WHERE id = ?
+            """,
+            (now, reason, reason, study_id),
+        )
+        conn.commit()
+        return True
+    except sqlite3.OperationalError:
+        return False
+    finally:
+        conn.close()
+
+
 def get_study_session_stats(days: int = 30) -> list[dict]:
     """Get study session stats grouped by course slug (or raw topic) for the given period."""
     conn = _connection._connect()