better-notion 1.5.5__py3-none-any.whl → 1.7.0__py3-none-any.whl

better_notion/_cli/docs/__init__.py

@@ -0,0 +1,20 @@
+"""Documentation system for AI agents.
+
+This module provides infrastructure for documenting CLI commands
+in a machine-readable format that AI agents can consume to understand
+the system at a high level of abstraction.
+"""
+
+from better_notion._cli.docs.base import (
+    Command,
+    Concept,
+    Schema,
+    Workflow,
+)
+
+__all__ = [
+    "Schema",
+    "Concept",
+    "Workflow",
+    "Command",
+]

better_notion/_cli/docs/base.py

@@ -0,0 +1,212 @@
+"""Base classes for documentation system.
+
+This module provides the core data structures for documenting
+CLI commands and workflows in a machine-readable format.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Concept:
+    """A concept represents a high-level idea in the system.
+
+    Concepts help AI agents understand what things are
+    (e.g., "workspace", "task", "version") beyond just
+    command syntax.
+
+    Attributes:
+        name: Name of the concept
+        description: Human-readable description
+        properties: Dict of concept properties and their meanings
+        relationships: Relationships to other concepts
+    """
+
+    name: str
+    description: str
+    properties: dict[str, Any] = field(default_factory=dict)
+    relationships: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "properties": self.properties,
+            "relationships": self.relationships,
+        }
+
+
+@dataclass
+class WorkflowStep:
+    """A single step in a workflow.
+
+    Attributes:
+        description: What this step does
+        command: Optional command to execute
+        purpose: Why this step is needed
+    """
+
+    description: str
+    command: str | None = None
+    purpose: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "description": self.description,
+            "command": self.command,
+            "purpose": self.purpose,
+        }
+
+
+@dataclass
+class ErrorRecovery:
+    """Error recovery strategy for a command.
+
+    Attributes:
+        error_type: Type of error (e.g., "workspace_exists")
+        message: Human-readable error message
+        solutions: List of possible solutions with flags/actions
+    """
+
+    error_type: str
+    message: str
+    solutions: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "error_type": self.error_type,
+            "message": self.message,
+            "solutions": self.solutions,
+        }
+
+
+@dataclass
+class Workflow:
+    """A workflow represents a sequence of operations.
+
+    Workflows help AI agents understand how to accomplish
+    high-level goals (e.g., "initialize_workspace",
+    "create_task").
+
+    Attributes:
+        name: Workflow name
+        description: What this workflow accomplishes
+        steps: List of steps in the workflow
+        commands: Example commands for this workflow
+        prerequisites: Required conditions before starting
+        error_recovery: Error handling strategies
+    """
+
+    name: str
+    description: str
+    steps: list[WorkflowStep | dict[str, Any]] = field(default_factory=list)
+    commands: list[str] = field(default_factory=list)
+    prerequisites: list[str] = field(default_factory=list)
+    error_recovery: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "steps": [
+                step.to_dict() if isinstance(step, WorkflowStep) else step
+                for step in self.steps
+            ],
+            "commands": self.commands,
+            "prerequisites": self.prerequisites,
+            "error_recovery": self.error_recovery,
+        }
+
+
+@dataclass
+class Command:
+    """Documentation for a single command.
+
+    Command docs go beyond --help text to provide semantic
+    meaning and workflow context.
+
+    Attributes:
+        name: Command name
+        purpose: What this command does (semantic meaning)
+        description: Detailed description
+        flags: Dict of flag -> purpose
+        workflow: Which workflow this command belongs to
+        when_to_use: When this command should be used
+        error_recovery: Error handling strategies
+        subcommands: Dict of subcommand name -> subcommand documentation
+    """
+
+    name: str
+    purpose: str
+    description: str = ""
+    flags: dict[str, str] = field(default_factory=dict)
+    workflow: str | None = None
+    when_to_use: list[str] = field(default_factory=list)
+    error_recovery: dict[str, dict[str, Any]] = field(default_factory=dict)
+    subcommands: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "name": self.name,
+            "purpose": self.purpose,
+            "description": self.description,
+            "flags": self.flags,
+            "workflow": self.workflow,
+            "when_to_use": self.when_to_use,
+            "error_recovery": self.error_recovery,
+        }
+
+        # Add subcommands if present
+        if self.subcommands:
+            result["subcommands"] = self.subcommands
+
+        return result
+
+
+@dataclass
+class Schema:
+    """Complete schema documentation for a plugin.
+
+    A Schema provides everything an AI agent needs to understand
+    a plugin system at a high level.
+
+    Attributes:
+        name: Plugin name
+        version: Schema version
+        description: Plugin description
+        concepts: High-level concepts in the system
+        workflows: Available workflows
+        commands: Command documentation
+        best_practices: Recommended usage patterns
+        examples: Usage examples
+    """
+
+    name: str
+    version: str
+    description: str
+    concepts: list[Concept] = field(default_factory=list)
+    workflows: list[Workflow] = field(default_factory=list)
+    commands: dict[str, Command] = field(default_factory=dict)
+    best_practices: list[str] = field(default_factory=list)
+    examples: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "concepts": [concept.to_dict() for concept in self.concepts],
+            "workflows": [workflow.to_dict() for workflow in self.workflows],
+            "commands": {
+                name: command.to_dict() for name, command in self.commands.items()
+            },
+            "best_practices": self.best_practices,
+            "examples": self.examples,
+        }

better_notion/_cli/docs/formatters.py

@@ -0,0 +1,128 @@
+"""Formatters for schema documentation.
+
+This module provides utilities to format Schema objects
+into different output formats (JSON, YAML).
+"""
+
+import json
+from typing import Any
+
+from better_notion._cli.docs.base import Schema
+
+
+def format_schema_json(schema: Schema, *, pretty: bool = True) -> str:
+    """Format a Schema as JSON.
+
+    Args:
+        schema: Schema object to format
+        pretty: Whether to pretty-print with indentation
+
+    Returns:
+        JSON string representation of the schema
+    """
+    schema_dict = schema.to_dict()
+    if pretty:
+        return json.dumps(schema_dict, indent=2)
+    return json.dumps(schema_dict)
+
+
+def format_schema_yaml(schema: Schema) -> str:
+    """Format a Schema as YAML.
+
+    Args:
+        schema: Schema object to format
+
+    Returns:
+        YAML string representation of the schema
+    """
+    try:
+        import yaml
+
+        return yaml.dump(schema.to_dict(), default_flow_style=False)
+    except ImportError:
+        # Fall back to JSON if pyyaml not installed
+        logger = __import__("logging").getLogger(__name__)
+        logger.warning("PyYAML not installed, falling back to JSON")
+        return format_schema_json(schema)
+
+
+def format_schema_pretty(schema: Schema) -> str:
+    """Format a Schema as human-readable text with sections.
+
+    This provides a more readable format for human consumption
+    while maintaining machine-parsable structure.
+
+    Args:
+        schema: Schema object to format
+
+    Returns:
+        Formatted text string
+    """
+    lines = []
+    data = schema.to_dict()
+
+    # Header
+    lines.append(f"# {schema.name.upper()} SCHEMA")
+    lines.append(f"Version: {schema.version}")
+    lines.append(f"Description: {schema.description}")
+    lines.append("")
+
+    # Concepts
+    if data["concepts"]:
+        lines.append("## CONCEPTS")
+        for concept in data["concepts"]:
+            lines.append(f"### {concept['name']}")
+            lines.append(f"{concept['description']}")
+            if concept.get("properties"):
+                lines.append("**Properties:**")
+                for key, value in concept["properties"].items():
+                    lines.append(f"  - {key}: {value}")
+            if concept.get("relationships"):
+                lines.append("**Relationships:**")
+                for key, value in concept["relationships"].items():
+                    lines.append(f"  - {key}: {value}")
+            lines.append("")
+
+    # Workflows
+    if data["workflows"]:
+        lines.append("## WORKFLOWS")
+        for workflow in data["workflows"]:
+            lines.append(f"### {workflow['name']}")
+            lines.append(f"{workflow['description']}")
+            if workflow.get("steps"):
+                lines.append("**Steps:**")
+                for i, step in enumerate(workflow["steps"], 1):
+                    if isinstance(step, dict):
+                        lines.append(f"  {i}. {step.get('description', step)}")
+                    else:
+                        lines.append(f"  {i}. {step}")
+            if workflow.get("commands"):
+                lines.append("**Commands:**")
+                for cmd in workflow["commands"]:
+                    lines.append(f"  - {cmd}")
+            lines.append("")
+
+    # Commands
+    if data["commands"]:
+        lines.append("## COMMANDS")
+        for cmd_name, cmd in data["commands"].items():
+            lines.append(f"### {cmd_name}")
+            lines.append(f"**Purpose:** {cmd.get('purpose', 'N/A')}")
+            if cmd.get("flags"):
+                lines.append("**Flags:**")
+                for flag, purpose in cmd["flags"].items():
+                    lines.append(f"  - {flag}: {purpose}")
+            if cmd.get("when_to_use"):
+                lines.append("**When to use:**")
+                for usage in cmd["when_to_use"]:
+                    lines.append(f"  - {usage}")
+            lines.append("")
+
+    # Best Practices
+    if data.get("best_practices"):
+        lines.append("## BEST PRACTICES")
+        for practice in data["best_practices"]:
+            lines.append(f"- {practice}")
+        lines.append("")
+
+    return "\n".join(lines)

better_notion/_cli/docs/registry.py

@@ -0,0 +1,82 @@
+"""Schema registry for plugin documentation.
+
+This module provides a central registry where plugins can register
+their documentation schemas for AI agent consumption.
+"""
+
+import logging
+from typing import Any
+
+from better_notion._cli.docs.base import Schema
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaRegistry:
+    """Registry for plugin documentation schemas.
+
+    This class maintains a collection of plugin schemas that
+    AI agents can query to understand the system.
+
+    Example:
+        >>> # Register a plugin schema
+        >>> SchemaRegistry.register("agents", AGENTS_SCHEMA)
+        >>>
+        >>> # Query for a plugin schema
+        >>> schema = SchemaRegistry.get("agents")
+        >>>
+        >>> # List all available schemas
+        >>> all_schemas = SchemaRegistry.list_all()
+    """
+
+    _schemas: dict[str, Schema] = {}
+
+    @classmethod
+    def register(cls, plugin_name: str, schema: Schema) -> None:
+        """Register a plugin schema.
+
+        Args:
+            plugin_name: Name of the plugin (e.g., "agents")
+            schema: Schema object containing plugin documentation
+        """
+        cls._schemas[plugin_name] = schema
+        logger.info(f"Registered schema for plugin: {plugin_name}")
+
+    @classmethod
+    def get(cls, plugin_name: str) -> Schema | None:
+        """Get a plugin schema by name.
+
+        Args:
+            plugin_name: Name of the plugin
+
+        Returns:
+            Schema object if found, None otherwise
+        """
+        return cls._schemas.get(plugin_name)
+
+    @classmethod
+    def list_all(cls) -> dict[str, Schema]:
+        """List all registered plugin schemas.
+
+        Returns:
+            Dict mapping plugin names to Schema objects
+        """
+        return cls._schemas.copy()
+
+    @classmethod
+    def get_all_names(cls) -> list[str]:
+        """Get list of all registered plugin names.
+
+        Returns:
+            List of plugin names
+        """
+        return list(cls._schemas.keys())
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered schemas.
+
+        This is primarily useful for testing.
+        """
+        cls._schemas.clear()
+        logger.debug("Cleared schema registry")

better_notion/_cli/main.py

@@ -118,6 +118,173 @@ def version(
         console.print(f"[bold blue]Better Notion CLI[/bold blue] version [bold green]{__version__}[/bold green]")
 
 
+@app.command()
+def docs(
+    topic: str = typer.Argument(None, help="Documentation topic to retrieve"),
+    format: str = typer.Option("json", "--format", "-f", help="Output format (json, yaml, pretty)"),
+) -> None:
+    """
+    Get system documentation for AI agents.
+
+    This command provides comprehensive documentation about the Better Notion CLI
+    that AI agents can consume to understand the system at a high level.
+
+    Without arguments: List all available topics
+    With topic: Show detailed documentation for that topic
+
+    Available topics:
+    - overview: System architecture and core concepts
+    - plugins: Available plugins and their capabilities
+    - commands: All available commands and their purposes
+
+    Examples:
+        $ notion docs                  # List all topics
+        $ notion docs overview         # Get system overview
+        $ notion docs overview --format json
+    """
+    import json
+
+    # Define available topics
+    topics = {
+        "overview": {
+            "name": "overview",
+            "title": "System Overview",
+            "description": "Better Notion CLI - Command-line interface for Notion API",
+            "version": __version__,
+            "architecture": {
+                "description": "A CLI for interacting with Notion, designed for AI agents",
+                "features": [
+                    "JSON-only output for programmatic parsing",
+                    "Structured error codes for reliable error handling",
+                    "Async command support for better performance",
+                    "Plugin system for extensibility",
+                ]
+            },
+            "core_concepts": [
+                {
+                    "name": "Pages",
+                    "description": "Notion pages with content blocks",
+                    "commands": ["notion pages get", "notion pages create", "notion pages update"]
+                },
+                {
+                    "name": "Databases",
+                    "description": "Notion databases with structured properties",
+                    "commands": ["notion databases get", "notion databases query", "notion databases create"]
+                },
+                {
+                    "name": "Blocks",
+                    "description": "Content blocks (paragraphs, headings, lists, etc.)",
+                    "commands": ["notion blocks get", "notion blocks create"]
+                },
+                {
+                    "name": "Plugins",
+                    "description": "Extensible command groups for specialized workflows",
+                    "commands": ["notion agents", "notion plugin list"]
+                }
+            ],
+            "getting_started": [
+                "1. Configure authentication: notion auth login",
+                "2. Check status: notion auth status",
+                "3. Get a page: notion pages get <page_id>"
+            ]
+        },
+        "plugins": {
+            "name": "plugins",
+            "title": "Available Plugins",
+            "description": "Official plugins that extend CLI functionality",
+            "plugins": [
+                {
+                    "name": "agents",
+                    "description": "Workflow management system for software development",
+                    "commands": ["agents init", "agents info", "agents schema"],
+                    "documentation": "Run 'notion agents schema' for complete documentation"
+                }
+            ]
+        },
+        "commands": {
+            "name": "commands",
+            "title": "Available Commands",
+            "description": "Core CLI commands organized by category",
+            "categories": [
+                {
+                    "name": "Authentication",
+                    "commands": [
+                        {"command": "notion auth login", "purpose": "Authenticate with Notion"},
+                        {"command": "notion auth status", "purpose": "Check authentication status"},
+                        {"command": "notion auth logout", "purpose": "Logout and clear credentials"}
+                    ]
+                },
+                {
+                    "name": "Pages",
+                    "commands": [
+                        {"command": "notion pages get <id>", "purpose": "Get page details"},
+                        {"command": "notion pages create", "purpose": "Create a new page"},
+                        {"command": "notion pages update <id>", "purpose": "Update page properties"},
+                        {"command": "notion pages search <query>", "purpose": "Search for pages"}
+                    ]
+                },
+                {
+                    "name": "Databases",
+                    "commands": [
+                        {"command": "notion databases get <id>", "purpose": "Get database details"},
+                        {"command": "notion databases query <id>", "purpose": "Query database with filters"},
+                        {"command": "notion databases create", "purpose": "Create a new database"}
+                    ]
+                },
+                {
+                    "name": "Blocks",
+                    "commands": [
+                        {"command": "notion blocks get <id>", "purpose": "Get block details"},
+                        {"command": "notion blocks children <id>", "purpose": "Get block children"}
+                    ]
+                }
+            ]
+        }
+    }
+
+    # If no topic specified, list available topics
+    if topic is None:
+        topics_list = {
+            "available_topics": [
+                {
+                    "name": name,
+                    "title": info["title"],
+                    "description": info["description"],
+                }
+                for name, info in topics.items()
+            ],
+            "usage": "notion docs <topic> for detailed information",
+            "examples": [
+                "notion docs overview",
+                "notion docs plugins",
+                "notion docs commands"
+            ]
+        }
+        typer.echo(json.dumps(topics_list, indent=2))
+        return
+
+    # Get the requested topic
+    topic_lower = topic.lower()
+    if topic_lower not in topics:
+        result = {
+            "success": False,
+            "error": {
+                "code": "UNKNOWN_TOPIC",
+                "message": f"Unknown topic: {topic}",
+                "retry": False,
+                "details": {
+                    "available_topics": list(topics.keys())
+                }
+            }
+        }
+        typer.echo(json.dumps(result, indent=2))
+        raise typer.Exit(code=1)
+
+    # Return the topic documentation
+    topic_info = topics[topic_lower]
+    typer.echo(json.dumps(topic_info, indent=2))
+
+
 @app.callback()
 def main(
     ctx: typer.Context,