better-notion 0.9.9__py3-none-any.whl → 1.0.1__py3-none-any.whl

better_notion/plugins/official/__init__.py

@@ -4,10 +4,12 @@ Official plugins for Better Notion CLI.
 This package contains officially maintained plugins that extend
 the CLI with commonly-needed functionality.
 """
+from better_notion.plugins.official.agents import AgentsPlugin
 from better_notion.plugins.official.productivity import ProductivityPlugin
 
-__all__ = ["ProductivityPlugin"]
+__all__ = ["AgentsPlugin", "ProductivityPlugin"]
 
 OFFICIAL_PLUGINS = [
+    AgentsPlugin,
     ProductivityPlugin,
 ]

better_notion/plugins/official/agents.py

@@ -0,0 +1,356 @@
+"""Official agents workflow management plugin for Better Notion CLI.
+
+This plugin provides comprehensive workflow management capabilities for coordinating
+AI agents working on software development projects through Notion.
+
+Features:
+    - Workspace initialization (creates all required databases)
+    - Project context management (.notion files)
+    - Role management (set and check current role)
+    - Task discovery and execution (claim, start, complete tasks)
+    - Idea capture and management
+    - Work issue tracking
+    - Dependency resolution
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from better_notion._cli.config import Config
+from better_notion._cli.response import format_error, format_success
+from better_notion._sdk.client import NotionClient
+from better_notion.plugins.base import PluginInterface
+from better_notion.utils.agents import (
+    DependencyResolver,
+    ProjectContext,
+    RoleManager,
+    get_or_create_agent_id,
+)
+from better_notion.utils.agents.workspace import WorkspaceInitializer, initialize_workspace_command
+
+
+def get_client() -> NotionClient:
+    """Get authenticated Notion client."""
+    config = Config.load()
+    return NotionClient(auth=config.token, timeout=config.timeout)
+
+
+class AgentsPlugin(PluginInterface):
+    """
+    Official agents workflow management plugin.
+
+    This plugin provides tools for managing software development workflows
+    through Notion databases, enabling AI agents to coordinate work on projects.
+
+    Commands:
+        - init: Initialize a new workspace with all databases
+        - init-project: Initialize a new project with .notion file
+        - role: Manage project role
+    """
+
+    def register_commands(self, app: typer.Typer) -> None:
+        """Register plugin commands with the CLI app."""
+        # Create agents command group
+        agents_app = typer.Typer(
+            name="agents",
+            help="Agents workflow management commands",
+        )
+
+        # Register sub-commands
+        @agents_app.command("init")
+        def init_workspace(
+            parent_page_id: str = typer.Option(
+                ...,
+                "--parent-page",
+                "-p",
+                help="ID of the parent page where databases will be created",
+            ),
+            workspace_name: str = typer.Option(
+                "Agents Workspace",
+                "--name",
+                "-n",
+                help="Name for the workspace",
+            ),
+        ) -> None:
+            """
+            Initialize a new workspace with all required databases.
+
+            Creates 8 databases in Notion with proper relationships:
+            - Organizations
+            - Projects
+            - Versions
+            - Tasks
+            - Ideas
+            - Work Issues
+            - Incidents
+            - Tags
+
+            Example:
+                $ notion agents init --parent-page page123 --name "My Workspace"
+            """
+            async def _init() -> str:
+                try:
+                    client = get_client()
+                    initializer = WorkspaceInitializer(client)
+
+                    database_ids = await initializer.initialize_workspace(
+                        parent_page_id=parent_page_id,
+                        workspace_name=workspace_name,
+                    )
+
+                    # Save database IDs
+                    initializer.save_database_ids()
+
+                    return format_success(
+                        {
+                            "message": "Workspace initialized successfully",
+                            "databases_created": len(database_ids),
+                            "database_ids": database_ids,
+                        }
+                    )
+
+                except Exception as e:
+                    return format_error("INIT_ERROR", str(e), retry=False)
+
+            result = asyncio.run(_init())
+            typer.echo(result)
+
+        @agents_app.command("init-project")
+        def init_project(
+            project_id: str = typer.Option(
+                ...,
+                "--project-id",
+                "-i",
+                help="Notion page ID for the project",
+            ),
+            project_name: str = typer.Option(
+                ...,
+                "--name",
+                "-n",
+                help="Project name",
+            ),
+            org_id: str = typer.Option(
+                ...,
+                "--org-id",
+                "-o",
+                help="Notion page ID for the organization",
+            ),
+            role: str = typer.Option(
+                "Developer",
+                "--role",
+                "-r",
+                help="Project role (default: Developer)",
+            ),
+        ) -> None:
+            """
+            Initialize a new project with a .notion file.
+
+            Creates a .notion file in the current directory that identifies
+            the project context for all CLI commands.
+
+            Example:
+                $ notion agents init-project \\
+                    --project-id page123 \\
+                    --name "My Project" \\
+                    --org-id org456 \\
+                    --role Developer
+            """
+            try:
+                # Validate role
+                if not RoleManager.is_valid_role(role):
+                    result = format_error(
+                        "INVALID_ROLE",
+                        f"Invalid role: {role}. Valid roles: {', '.join(RoleManager.get_all_roles())}",
+                        retry=False,
+                    )
+                else:
+                    # Create .notion file
+                    context = ProjectContext.create(
+                        project_id=project_id,
+                        project_name=project_name,
+                        org_id=org_id,
+                        role=role,
+                        path=Path.cwd(),
+                    )
+
+                    result = format_success(
+                        {
+                            "message": "Project initialized successfully",
+                            "project_id": context.project_id,
+                            "project_name": context.project_name,
+                            "org_id": context.org_id,
+                            "role": context.role,
+                            "notion_file": str(Path.cwd() / ".notion"),
+                        }
+                    )
+
+            except Exception as e:
+                result = format_error("INIT_PROJECT_ERROR", str(e), retry=False)
+
+            typer.echo(result)
+
+        # Role management commands
+        role_app = typer.Typer(
+            name="role",
+            help="Role management commands",
+        )
+        agents_app.add_typer(role_app)
+
+        @role_app.command("be")
+        def role_be(
+            new_role: str = typer.Argument(..., help="Role to set"),
+            path: Optional[Path] = typer.Option(
+                None, "--path", "-p", help="Path to project directory (default: cwd)"
+            ),
+        ) -> None:
+            """
+            Set the project role.
+
+            Updates the role in the .notion file. The role determines what
+            actions the agent can perform in this project.
+
+            Example:
+                $ notion agents role be PM
+                $ notion agents role be Developer --path /path/to/project
+            """
+            try:
+                # Validate role
+                if not RoleManager.is_valid_role(new_role):
+                    result = format_error(
+                        "INVALID_ROLE",
+                        f"Invalid role: {new_role}. Valid roles: {', '.join(RoleManager.get_all_roles())}",
+                        retry=False,
+                    )
+                else:
+                    # Load project context
+                    if path:
+                        context = ProjectContext.from_path(path)
+                    else:
+                        context = ProjectContext.from_current_directory()
+
+                    if not context:
+                        result = format_error(
+                            "NO_PROJECT_CONTEXT",
+                            "No .notion file found. Are you in a project directory?",
+                            retry=False,
+                        )
+                    else:
+                        # Update role
+                        context.update_role(new_role, path=path or None)
+
+                        result = format_success(
+                            {
+                                "message": f"Role updated to {new_role}",
+                                "previous_role": context.role,
+                                "new_role": new_role,
+                            }
+                        )
+
+            except Exception as e:
+                result = format_error("ROLE_UPDATE_ERROR", str(e), retry=False)
+
+            typer.echo(result)
+
+        @role_app.command("whoami")
+        def role_whoami(
+            path: Optional[Path] = typer.Option(
+                None, "--path", "-p", help="Path to project directory (default: cwd)"
+            ),
+        ) -> None:
+            """
+            Show the current project role.
+
+            Displays the role from the .notion file in the current or
+            specified project directory.
+
+            Example:
+                $ notion agents role whoami
+                $ notion agents role whoami --path /path/to/project
+            """
+            try:
+                # Load project context
+                if path:
+                    context = ProjectContext.from_path(path)
+                else:
+                    context = ProjectContext.from_current_directory()
+
+                if not context:
+                    result = format_error(
+                        "NO_PROJECT_CONTEXT",
+                        "No .notion file found. Are you in a project directory?",
+                        retry=False,
+                    )
+                else:
+                    # Get role description
+                    description = RoleManager.get_role_description(context.role)
+
+                    result = format_success(
+                        {
+                            "role": context.role,
+                            "description": description,
+                            "project": context.project_name,
+                            "permissions": RoleManager.get_permissions(context.role),
+                        }
+                    )
+
+            except Exception as e:
+                result = format_error("ROLE_ERROR", str(e), retry=False)
+
+            typer.echo(result)
+
+        @role_app.command("list")
+        def role_list() -> None:
+            """
+            List all available roles.
+
+            Shows all valid roles that can be used in the workflow system.
+
+            Example:
+                $ notion agents role list
+            """
+            try:
+                roles = RoleManager.get_all_roles()
+
+                role_info = []
+                for role in roles:
+                    description = RoleManager.get_role_description(role)
+                    permissions = RoleManager.get_permissions(role)
+                    role_info.append(
+                        {
+                            "role": role,
+                            "description": description,
+                            "permission_count": len(permissions),
+                        }
+                    )
+
+                result = format_success(
+                    {
+                        "roles": role_info,
+                        "total": len(roles),
+                    }
+                )
+
+            except Exception as e:
+                result = format_error("ROLE_LIST_ERROR", str(e), retry=False)
+
+            typer.echo(result)
+
+        # Register agents app to main CLI
+        app.add_typer(agents_app)
+
+    def get_info(self) -> dict[str, str | bool | list]:
+        """Return plugin metadata."""
+        return {
+            "name": "agents",
+            "version": "1.0.0",
+            "description": "Workflow management system for AI agents coordinating on software development projects",
+            "author": "Better Notion Team",
+            "official": True,
+            "category": "workflow",
+            "dependencies": [],
+        }

better_notion/utils/agents/__init__.py

@@ -0,0 +1,65 @@
+"""Utility functions and classes for agents workflow management."""
+
+from better_notion.utils.agents.auth import (
+    AgentContext,
+    clear_agent_id,
+    get_agent_id_path,
+    get_agent_info,
+    get_or_create_agent_id,
+    is_valid_agent_id,
+    set_agent_id,
+)
+from better_notion.utils.agents.dependency_resolver import DependencyResolver
+from better_notion.utils.agents.project_context import ProjectContext
+from better_notion.utils.agents.rbac import RoleManager
+from better_notion.utils.agents.schemas import (
+    IncidentSchema,
+    IdeaSchema,
+    OrganizationSchema,
+    ProjectSchema,
+    PropertyBuilder,
+    SelectOption,
+    TagSchema,
+    TaskSchema,
+    VersionSchema,
+    WorkIssueSchema,
+)
+from better_notion.utils.agents.state_machine import TaskStatus, TaskStateMachine
+from better_notion.utils.agents.workspace import (
+    WorkspaceInitializer,
+    initialize_workspace_command,
+)
+
+__all__ = [
+    # Agent authentication
+    "AgentContext",
+    "clear_agent_id",
+    "get_agent_id_path",
+    "get_agent_info",
+    "get_or_create_agent_id",
+    "is_valid_agent_id",
+    "set_agent_id",
+    # Dependency resolution
+    "DependencyResolver",
+    # Project context
+    "ProjectContext",
+    # Role-based access control
+    "RoleManager",
+    # Database schemas
+    "IncidentSchema",
+    "IdeaSchema",
+    "OrganizationSchema",
+    "ProjectSchema",
+    "PropertyBuilder",
+    "SelectOption",
+    "TagSchema",
+    "TaskSchema",
+    "VersionSchema",
+    "WorkIssueSchema",
+    # State machine
+    "TaskStatus",
+    "TaskStateMachine",
+    # Workspace initialization
+    "WorkspaceInitializer",
+    "initialize_workspace_command",
+]

better_notion/utils/agents/auth.py

@@ -0,0 +1,235 @@
+"""Agent authentication and identification for the agents workflow system.
+
+This module provides agent identification and tracking functionality. Each agent
+gets a unique ID that is stored locally and used for tracking operations across
+workflow commands.
+"""
+
+import json
+import uuid
+from pathlib import Path
+from typing import Optional
+
+
+# Default path for agent ID storage
+AGENT_ID_FILE = Path.home() / ".notion" / "agent_id"
+
+
+def get_agent_id_path() -> Path:
+    """Get the path to the agent ID file.
+
+    Returns:
+        Path to the agent ID file
+
+    Example:
+        >>> path = get_agent_id_path()
+        >>> print(path)
+        PosixPath('/Users/user/.notion/agent_id')
+    """
+    return AGENT_ID_FILE
+
+
+def get_or_create_agent_id() -> str:
+    """Get existing agent ID or create a new one.
+
+    This function checks if an agent ID file exists in ~/.notion/agent_id.
+    If it exists, it reads and returns the ID. If not, it generates a new
+    UUID-based agent ID and stores it.
+
+    Returns:
+        Agent ID string (format: "agent-{uuid}")
+
+    Example:
+        >>> agent_id = get_or_create_agent_id()
+        >>> print(agent_id)
+        'agent-1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p'
+    """
+    # Ensure directory exists
+    AGENT_ID_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    # Check if agent ID file exists
+    if AGENT_ID_FILE.exists() and AGENT_ID_FILE.is_file():
+        try:
+            with open(AGENT_ID_FILE, encoding="utf-8") as f:
+                content = f.read().strip()
+
+            if content:
+                return content
+
+        except (IOError, OSError):
+            # File exists but can't be read
+            # Fall through to create new ID
+            pass
+
+    # Generate new agent ID
+    agent_id = f"agent-{uuid.uuid4()}"
+
+    # Save to file
+    try:
+        with open(AGENT_ID_FILE, "w", encoding="utf-8") as f:
+            f.write(agent_id)
+    except (IOError, OSError) as e:
+        # Can't save agent ID - log warning but continue
+        # The agent can still function with a temporary ID
+        pass
+
+    return agent_id
+
+
+def set_agent_id(agent_id: str) -> bool:
+    """Set a specific agent ID (useful for testing or manual configuration).
+
+    Args:
+        agent_id: Agent ID to set
+
+    Returns:
+        True if agent ID was saved successfully, False otherwise
+
+    Example:
+        >>> success = set_agent_id("agent-custom-id-123")
+        >>> print(success)
+        True
+    """
+    # Ensure directory exists
+    AGENT_ID_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with open(AGENT_ID_FILE, "w", encoding="utf-8") as f:
+            f.write(agent_id.strip())
+
+        return True
+
+    except (IOError, OSError):
+        return False
+
+
+def clear_agent_id() -> bool:
+    """Clear the stored agent ID.
+
+    This is useful for testing or when you want to generate a fresh agent ID.
+
+    Returns:
+        True if agent ID was cleared successfully, False otherwise
+
+    Example:
+        >>> clear_agent_id()
+        True
+        >>> new_id = get_or_create_agent_id()
+        >>> # Will generate a new ID
+    """
+    try:
+        if AGENT_ID_FILE.exists():
+            AGENT_ID_FILE.unlink()
+
+        return True
+
+    except (IOError, OSError):
+        return False
+
+
+def is_valid_agent_id(agent_id: str) -> bool:
+    """Check if a string is a valid agent ID format.
+
+    Valid agent IDs must start with "agent-" followed by a UUID.
+
+    Args:
+        agent_id: Agent ID string to validate
+
+    Returns:
+        True if agent ID is valid format, False otherwise
+
+    Example:
+        >>> is_valid_agent_id("agent-1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p")
+        True
+
+        >>> is_valid_agent_id("invalid-id")
+        False
+    """
+    if not agent_id.startswith("agent-"):
+        return False
+
+    # Extract UUID part
+    uuid_part = agent_id[6:]  # Remove "agent-" prefix
+
+    try:
+        # Try to parse as UUID
+        uuid.UUID(uuid_part)
+        return True
+
+    except ValueError:
+        return False
+
+
+def get_agent_info() -> dict[str, str]:
+    """Get complete agent information including ID and metadata.
+
+    Returns:
+        Dict with agent information:
+        - agent_id: The agent's unique identifier
+        - agent_id_exists: Whether the agent ID file exists
+        - agent_id_path: Path to the agent ID file
+
+    Example:
+        >>> info = get_agent_info()
+        >>> print(info['agent_id'])
+        'agent-1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p'
+    """
+    return {
+        "agent_id": get_or_create_agent_id(),
+        "agent_id_exists": AGENT_ID_FILE.exists(),
+        "agent_id_path": str(AGENT_ID_FILE),
+    }
+
+
+class AgentContext:
+    """Context manager for temporary agent ID overrides.
+
+    This is useful for testing when you want to temporarily use a different
+    agent ID without affecting the stored ID.
+
+    Example:
+        >>> with AgentContext("agent-test-123"):
+        ...     agent_id = get_or_create_agent_id()
+        ...     print(agent_id)  # "agent-test-123"
+        >>> # Back to normal agent ID
+    """
+
+    def __init__(self, temp_agent_id: str):
+        """Initialize the context manager.
+
+        Args:
+            temp_agent_id: Temporary agent ID to use during context
+        """
+        self.temp_agent_id = temp_agent_id
+        self.original_id: Optional[str] = None
+        self.file_existed: bool = False
+
+    def __enter__(self) -> "AgentContext":
+        """Enter the context and save original agent ID."""
+        # Save original ID if file exists
+        if AGENT_ID_FILE.exists():
+            self.file_existed = True
+            try:
+                with open(AGENT_ID_FILE, encoding="utf-8") as f:
+                    self.original_id = f.read().strip()
+            except (IOError, OSError):
+                self.original_id = None
+
+        # Set temporary ID
+        set_agent_id(self.temp_agent_id)
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context and restore original agent ID."""
+        if self.original_id:
+            # Restore original ID
+            set_agent_id(self.original_id)
+        elif self.file_existed:
+            # File existed but couldn't read - clear it
+            clear_agent_id()
+        else:
+            # File didn't exist - remove the temp file
+            clear_agent_id()
+
+        return None