mng-tutor 0.1.1__tar.gz

mng_tutor-0.1.1/.gitignore

@@ -0,0 +1,270 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+.venv-*
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# task folders for local custom claude workflow
+*/*/_tasks/
+.sesskey
+
+# Node.js
+node_modules/
+
+# Frontend build artifacts
+frontend-dist/
+
+# ignore review files
+.reviews/
+
+# files necessary to smuggle session id into reviewers
+.claude/sessionid
+
+# Claude Code local settings (session-specific permissions)
+.claude/settings.local.json
+
+# PR status and URL files written by main_claude_stop_hook.sh for status line display
+.claude/pr_url
+.claude/pr_status
+
+# History of commits reviewed by main_claude_stop_hook.sh (to detect stuck agents)
+.claude/reviewed_commits
+
+# Local Claude settings backup files
+.claude/*.bak
+
+# Local mng settings (not committed)
+.mng/settings.local.toml
+
+# so the user can make their own notification script
+scripts/notify_user.local.sh
+
+# Test output files (slow tests, coverage summaries)
+.test_output/
+
+# Active session marker file (used to detect interrupted sessions)
+.claude/active
+
+# we stick the image build artifacts here
+.mng/dev/build/
+.mng/dev/secrets/
+
+# Offload caches and local files
+.offload/**
+test-results/**
+current.tar.gz
+
+# Changelings deploy-time build artifacts
+.changelings/
+
+# Autofix working artifacts
+.autofix/
+
+# Demo recordings (asciinema .cast, .txt, and scripts)
+.demos/
+
+# for git worktrees from other repos
+.external_worktrees/

mng_tutor-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mng-tutor
+Version: 0.1.1
+Summary: Interactive tutorial plugin for mng
+Requires-Python: >=3.11
+Requires-Dist: click-option-group>=0.5.6
+Requires-Dist: click>=8.0
+Requires-Dist: mng==0.1.6

mng_tutor-0.1.1/conftest.py

@@ -0,0 +1,15 @@
+"""Project-level conftest for mng-tutor.
+
+When running tests from libs/mng_tutor/, this conftest provides the common pytest hooks
+that would otherwise come from the monorepo root conftest.py (which is not discovered
+when pytest runs from a subdirectory).
+
+When running from the monorepo root, the root conftest.py registers the hooks first,
+and this file's register_conftest_hooks() call is a no-op (guarded by a module-level flag).
+"""
+
+from imbue.imbue_common.conftest_hooks import register_conftest_hooks
+from imbue.mng.utils.logging import suppress_warnings
+
+suppress_warnings()
+register_conftest_hooks(globals())

mng_tutor-0.1.1/imbue/mng_tutor/checks.py

@@ -0,0 +1,95 @@
+import subprocess
+from typing import assert_never
+
+from loguru import logger
+
+from imbue.mng.api.list import list_agents
+from imbue.mng.config.data_types import MngContext
+from imbue.mng.errors import BaseMngError
+from imbue.mng.interfaces.data_types import AgentDetails
+from imbue.mng.primitives import AgentLifecycleState
+from imbue.mng.primitives import AgentName
+from imbue.mng.primitives import ErrorBehavior
+from imbue.mng_tutor.data_types import AgentExistsCheck
+from imbue.mng_tutor.data_types import AgentInStateCheck
+from imbue.mng_tutor.data_types import AgentNotExistsCheck
+from imbue.mng_tutor.data_types import FileExistsInAgentWorkDirCheck
+from imbue.mng_tutor.data_types import StepCheck
+from imbue.mng_tutor.data_types import TmuxSessionHasClientsCheck
+
+
+def _find_agent_by_name(agent_name: AgentName, mng_ctx: MngContext) -> AgentDetails | None:
+    """Find an agent by name, returning None if not found."""
+    result = list_agents(mng_ctx, is_streaming=False, error_behavior=ErrorBehavior.CONTINUE)
+    for agent in result.agents:
+        if agent.name == agent_name:
+            return agent
+    return None
+
+
+def _check_agent_exists(agent_name: AgentName, mng_ctx: MngContext) -> bool:
+    """Check if an agent with the given name exists."""
+    return _find_agent_by_name(agent_name, mng_ctx) is not None
+
+
+def _check_agent_in_state(
+    agent_name: AgentName,
+    expected_states: tuple[AgentLifecycleState, ...],
+    mng_ctx: MngContext,
+) -> bool:
+    """Check if an agent is in one of the expected lifecycle states."""
+    agent = _find_agent_by_name(agent_name, mng_ctx)
+    if agent is None:
+        return False
+    return agent.state in expected_states
+
+
+def _check_file_exists_in_work_dir(
+    agent_name: AgentName,
+    file_path: str,
+    mng_ctx: MngContext,
+) -> bool:
+    """Check if a file exists in the agent's working directory."""
+    agent = _find_agent_by_name(agent_name, mng_ctx)
+    if agent is None:
+        return False
+    full_path = agent.work_dir / file_path
+    return full_path.exists()
+
+
+def _check_tmux_session_has_clients(agent_name: AgentName, mng_ctx: MngContext) -> bool:
+    """Check if the agent's tmux session has at least one attached client."""
+    session_name = f"{mng_ctx.config.prefix}{agent_name}"
+    result = subprocess.run(
+        ["tmux", "list-clients", "-t", session_name],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return False
+    return len(result.stdout.strip()) > 0
+
+
+def _execute_check(check: StepCheck, mng_ctx: MngContext) -> bool:
+    """Execute the check logic for a single step."""
+    if isinstance(check, AgentExistsCheck):
+        return _check_agent_exists(check.agent_name, mng_ctx)
+    elif isinstance(check, AgentNotExistsCheck):
+        return not _check_agent_exists(check.agent_name, mng_ctx)
+    elif isinstance(check, AgentInStateCheck):
+        return _check_agent_in_state(check.agent_name, check.expected_states, mng_ctx)
+    elif isinstance(check, FileExistsInAgentWorkDirCheck):
+        return _check_file_exists_in_work_dir(check.agent_name, check.file_path, mng_ctx)
+    elif isinstance(check, TmuxSessionHasClientsCheck):
+        return _check_tmux_session_has_clients(check.agent_name, mng_ctx)
+    else:
+        assert_never(check)
+
+
+def run_check(check: StepCheck, mng_ctx: MngContext) -> bool:
+    """Execute a step check and return whether it passes."""
+    try:
+        return _execute_check(check, mng_ctx)
+    except (BaseMngError, OSError):
+        logger.debug("Check failed with exception for check type: {}", type(check).__name__)
+        return False

mng_tutor-0.1.1/imbue/mng_tutor/checks_test.py

@@ -0,0 +1,43 @@
+import pytest
+
+from imbue.mng.config.data_types import MngContext
+from imbue.mng.primitives import AgentLifecycleState
+from imbue.mng.primitives import AgentName
+from imbue.mng_tutor.checks import run_check
+from imbue.mng_tutor.data_types import AgentExistsCheck
+from imbue.mng_tutor.data_types import AgentInStateCheck
+from imbue.mng_tutor.data_types import AgentNotExistsCheck
+from imbue.mng_tutor.data_types import FileExistsInAgentWorkDirCheck
+from imbue.mng_tutor.data_types import TmuxSessionHasClientsCheck
+
+
+def test_agent_exists_check_returns_false_when_no_agents(temp_mng_ctx: MngContext) -> None:
+    check = AgentExistsCheck(agent_name=AgentName("nonexistent"))
+    assert run_check(check, temp_mng_ctx) is False
+
+
+def test_agent_not_exists_check_returns_true_when_no_agents(temp_mng_ctx: MngContext) -> None:
+    check = AgentNotExistsCheck(agent_name=AgentName("nonexistent"))
+    assert run_check(check, temp_mng_ctx) is True
+
+
+def test_agent_in_state_check_returns_false_when_no_agents(temp_mng_ctx: MngContext) -> None:
+    check = AgentInStateCheck(
+        agent_name=AgentName("nonexistent"),
+        expected_states=(AgentLifecycleState.RUNNING,),
+    )
+    assert run_check(check, temp_mng_ctx) is False
+
+
+def test_file_exists_check_returns_false_when_no_agents(temp_mng_ctx: MngContext) -> None:
+    check = FileExistsInAgentWorkDirCheck(
+        agent_name=AgentName("nonexistent"),
+        file_path="hello.txt",
+    )
+    assert run_check(check, temp_mng_ctx) is False
+
+
+@pytest.mark.tmux
+def test_tmux_session_has_clients_check_returns_false_when_no_session(temp_mng_ctx: MngContext) -> None:
+    check = TmuxSessionHasClientsCheck(agent_name=AgentName("nonexistent"))
+    assert run_check(check, temp_mng_ctx) is False

mng_tutor-0.1.1/imbue/mng_tutor/cli.py

@@ -0,0 +1,56 @@
+from typing import Any
+
+import click
+
+from imbue.mng.cli.common_opts import CommonCliOptions
+from imbue.mng.cli.common_opts import add_common_options
+from imbue.mng.cli.common_opts import setup_command_context
+from imbue.mng.cli.help_formatter import CommandHelpMetadata
+from imbue.mng.cli.help_formatter import add_pager_help_option
+from imbue.mng_tutor.lessons import ALL_LESSONS
+from imbue.mng_tutor.tui import run_lesson_runner
+from imbue.mng_tutor.tui import run_lesson_selector
+
+
+class TutorCliOptions(CommonCliOptions):
+    """Options for the tutor command."""
+
+
+@click.command()
+@add_common_options
+@click.pass_context
+def tutor(ctx: click.Context, **kwargs: Any) -> None:
+    mng_ctx, output_opts, opts = setup_command_context(
+        ctx=ctx,
+        command_name="tutor",
+        command_class=TutorCliOptions,
+    )
+
+    # Loop: select a lesson, run it, return to selector when done
+    lesson = run_lesson_selector(ALL_LESSONS)
+    while lesson is not None:
+        run_lesson_runner(lesson, mng_ctx)
+        lesson = run_lesson_selector(ALL_LESSONS)
+
+
+CommandHelpMetadata(
+    key="tutor",
+    one_line_description="Interactive tutorial for learning mng commands",
+    synopsis="mng tutor [OPTIONS]",
+    description="""Launches an interactive tutorial that guides you through learning
+mng commands step by step. Run this in a separate terminal from your
+main working terminal.
+
+Each lesson contains a series of steps with automatic completion detection.
+Follow the instructions in the tutor terminal and complete each step in
+your other terminal. The tutor automatically detects when each step is
+complete and advances to the next one.""",
+    examples=(("Start the interactive tutor", "mng tutor"),),
+    see_also=(
+        ("create", "Create a new agent"),
+        ("connect", "Connect to an agent"),
+        ("list", "List agents"),
+    ),
+).register()
+
+add_pager_help_option(tutor)

mng_tutor-0.1.1/imbue/mng_tutor/conftest.py

@@ -0,0 +1,9 @@
+"""Test fixtures for mng-tutor.
+
+Uses shared plugin test fixtures from mng for common setup (plugin manager,
+environment isolation, git repos, temp_mng_ctx, local_provider, etc.).
+"""
+
+from imbue.mng.utils.plugin_testing import register_plugin_test_fixtures
+
+register_plugin_test_fixtures(globals())

mng_tutor-0.1.1/imbue/mng_tutor/data_types.py

@@ -0,0 +1,72 @@
+from typing import Annotated
+from typing import Literal
+
+from pydantic import Discriminator
+from pydantic import Field
+
+from imbue.imbue_common.frozen_model import FrozenModel
+from imbue.mng.primitives import AgentLifecycleState
+from imbue.mng.primitives import AgentName
+
+
+class AgentExistsCheck(FrozenModel):
+    """Check that an agent with the given name exists."""
+
+    check_type: Literal["agent_exists"] = "agent_exists"
+    agent_name: AgentName = Field(description="Name of the agent to check for")
+
+
+class AgentNotExistsCheck(FrozenModel):
+    """Check that an agent with the given name does not exist."""
+
+    check_type: Literal["agent_not_exists"] = "agent_not_exists"
+    agent_name: AgentName = Field(description="Name of the agent to check for")
+
+
+class AgentInStateCheck(FrozenModel):
+    """Check that an agent is in one of the expected lifecycle states."""
+
+    check_type: Literal["agent_in_state"] = "agent_in_state"
+    agent_name: AgentName = Field(description="Name of the agent to check")
+    expected_states: tuple[AgentLifecycleState, ...] = Field(description="Acceptable lifecycle states")
+
+
+class FileExistsInAgentWorkDirCheck(FrozenModel):
+    """Check that a file exists in an agent's working directory."""
+
+    check_type: Literal["file_exists_in_work_dir"] = "file_exists_in_work_dir"
+    agent_name: AgentName = Field(description="Name of the agent whose work_dir to check")
+    file_path: str = Field(description="Relative path within the agent's work_dir")
+
+
+class TmuxSessionHasClientsCheck(FrozenModel):
+    """Check that an agent's tmux session has at least one attached client."""
+
+    check_type: Literal["tmux_session_has_clients"] = "tmux_session_has_clients"
+    agent_name: AgentName = Field(description="Name of the agent whose tmux session to check")
+
+
+StepCheck = Annotated[
+    AgentExistsCheck
+    | AgentNotExistsCheck
+    | AgentInStateCheck
+    | FileExistsInAgentWorkDirCheck
+    | TmuxSessionHasClientsCheck,
+    Discriminator("check_type"),
+]
+
+
+class LessonStep(FrozenModel):
+    """A single step in a tutorial lesson."""
+
+    heading: str = Field(description="Short heading for the step")
+    details: str = Field(description="Detailed instructions for completing the step")
+    check: StepCheck = Field(description="How to verify the step is complete")
+
+
+class Lesson(FrozenModel):
+    """A complete tutorial lesson with ordered steps."""
+
+    title: str = Field(description="Title of the lesson")
+    description: str = Field(description="Brief description of what this lesson teaches")
+    steps: tuple[LessonStep, ...] = Field(description="Ordered steps to complete")

mng_tutor-0.1.1/imbue/mng_tutor/data_types_test.py

@@ -0,0 +1,101 @@
+from imbue.mng.primitives import AgentLifecycleState
+from imbue.mng.primitives import AgentName
+from imbue.mng_tutor.data_types import AgentExistsCheck
+from imbue.mng_tutor.data_types import AgentInStateCheck
+from imbue.mng_tutor.data_types import AgentNotExistsCheck
+from imbue.mng_tutor.data_types import FileExistsInAgentWorkDirCheck
+from imbue.mng_tutor.data_types import Lesson
+from imbue.mng_tutor.data_types import LessonStep
+from imbue.mng_tutor.data_types import TmuxSessionHasClientsCheck
+
+
+def test_agent_exists_check_construction() -> None:
+    check = AgentExistsCheck(agent_name=AgentName("test-agent"))
+    assert check.check_type == "agent_exists"
+    assert check.agent_name == AgentName("test-agent")
+
+
+def test_agent_not_exists_check_construction() -> None:
+    check = AgentNotExistsCheck(agent_name=AgentName("test-agent"))
+    assert check.check_type == "agent_not_exists"
+    assert check.agent_name == AgentName("test-agent")
+
+
+def test_agent_in_state_check_construction() -> None:
+    check = AgentInStateCheck(
+        agent_name=AgentName("test-agent"),
+        expected_states=(AgentLifecycleState.RUNNING,),
+    )
+    assert check.check_type == "agent_in_state"
+    assert check.agent_name == AgentName("test-agent")
+    assert check.expected_states == (AgentLifecycleState.RUNNING,)
+
+
+def test_agent_in_state_check_accepts_multiple_states() -> None:
+    check = AgentInStateCheck(
+        agent_name=AgentName("test-agent"),
+        expected_states=(AgentLifecycleState.RUNNING, AgentLifecycleState.WAITING),
+    )
+    assert len(check.expected_states) == 2
+
+
+def test_file_exists_check_construction() -> None:
+    check = FileExistsInAgentWorkDirCheck(
+        agent_name=AgentName("test-agent"),
+        file_path="hello.txt",
+    )
+    assert check.check_type == "file_exists_in_work_dir"
+    assert check.agent_name == AgentName("test-agent")
+    assert check.file_path == "hello.txt"
+
+
+def test_tmux_session_has_clients_check_construction() -> None:
+    check = TmuxSessionHasClientsCheck(agent_name=AgentName("test-agent"))
+    assert check.check_type == "tmux_session_has_clients"
+    assert check.agent_name == AgentName("test-agent")
+
+
+def test_lesson_step_with_agent_exists_check() -> None:
+    step = LessonStep(
+        heading="Create an agent",
+        details="Run `mng create test-agent`.",
+        check=AgentExistsCheck(agent_name=AgentName("test-agent")),
+    )
+    assert step.heading == "Create an agent"
+    assert isinstance(step.check, AgentExistsCheck)
+
+
+def test_lesson_step_with_agent_in_state_check() -> None:
+    step = LessonStep(
+        heading="Stop the agent",
+        details="Run `mng stop test-agent`.",
+        check=AgentInStateCheck(
+            agent_name=AgentName("test-agent"),
+            expected_states=(AgentLifecycleState.STOPPED,),
+        ),
+    )
+    assert isinstance(step.check, AgentInStateCheck)
+    assert step.check.expected_states == (AgentLifecycleState.STOPPED,)
+
+
+def test_lesson_construction() -> None:
+    lesson = Lesson(
+        title="Test Lesson",
+        description="A test lesson.",
+        steps=(
+            LessonStep(
+                heading="Step 1",
+                details="Do step 1.",
+                check=AgentExistsCheck(agent_name=AgentName("agent-1")),
+            ),
+            LessonStep(
+                heading="Step 2",
+                details="Do step 2.",
+                check=AgentNotExistsCheck(agent_name=AgentName("agent-1")),
+            ),
+        ),
+    )
+    assert lesson.title == "Test Lesson"
+    assert len(lesson.steps) == 2
+    assert isinstance(lesson.steps[0].check, AgentExistsCheck)
+    assert isinstance(lesson.steps[1].check, AgentNotExistsCheck)