htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/docs/metadata.py

@@ -0,0 +1,93 @@
+"""
+Documentation metadata storage and management.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class DocsMetadata(BaseModel):
+    """Metadata for project documentation."""
+
+    schema_version: int = 2
+    last_updated: datetime = Field(default_factory=datetime.now)
+    customizations: list[str] = []  # List of user-customized sections
+    base_version_on_last_update: str = "0.21.0"
+
+    @classmethod
+    def load(cls, htmlgraph_dir: Path) -> "DocsMetadata":
+        """Load metadata from .docs-metadata.json.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+
+        Returns:
+            DocsMetadata instance (default if file doesn't exist)
+        """
+        import json
+
+        metadata_file = htmlgraph_dir / ".docs-metadata.json"
+        if metadata_file.exists():
+            data = json.loads(metadata_file.read_text())
+            return cls(**data)
+        return cls()  # Default
+
+    def save(self, htmlgraph_dir: Path) -> None:
+        """Save metadata to .docs-metadata.json.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+        """
+        metadata_file = htmlgraph_dir / ".docs-metadata.json"
+        metadata_file.write_text(self.model_dump_json(indent=2))
+
+    @classmethod
+    def create_initial(
+        cls, htmlgraph_dir: Path, schema_version: int = 2
+    ) -> "DocsMetadata":
+        """Create initial metadata file.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            schema_version: Documentation schema version
+
+        Returns:
+            New DocsMetadata instance
+        """
+        from htmlgraph import __version__
+
+        metadata = cls(
+            schema_version=schema_version,
+            base_version_on_last_update=__version__,
+            customizations=[],
+        )
+        metadata.save(htmlgraph_dir)
+        return metadata
+
+    def add_customization(self, section_name: str) -> None:
+        """Mark a section as customized.
+
+        Args:
+            section_name: Name of the customized section
+        """
+        if section_name not in self.customizations:
+            self.customizations.append(section_name)
+
+    def remove_customization(self, section_name: str) -> None:
+        """Remove a customization marker.
+
+        Args:
+            section_name: Name of the section to unmark
+        """
+        if section_name in self.customizations:
+            self.customizations.remove(section_name)
+
+    def has_customizations(self) -> bool:
+        """Check if any customizations exist.
+
+        Returns:
+            True if user has customized documentation
+        """
+        return len(self.customizations) > 0

htmlgraph/docs/migrations.py

@@ -0,0 +1,232 @@
+"""
+Documentation migration system.
+
+Handles version migrations with automatic customization preservation.
+"""
+
+import shutil
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+
+from htmlgraph.docs.metadata import DocsMetadata
+
+
+class MigrationScript(ABC):
+    """Base class for documentation migrations."""
+
+    from_version: int
+    to_version: int
+
+    @abstractmethod
+    def migrate(self, htmlgraph_dir: Path, backup_dir: Path) -> bool:
+        """Execute migration. Returns True if successful.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            True if migration successful
+        """
+        pass
+
+    @abstractmethod
+    def rollback(self, htmlgraph_dir: Path, backup_dir: Path) -> None:
+        """Rollback migration to previous state.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+        """
+        pass
+
+    def backup_docs(self, htmlgraph_dir: Path, backup_dir: Path) -> Path:
+        """Backup current documentation before migration.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            Path to created backup subdirectory
+        """
+        backup_subdir = (
+            backup_dir / f"v{self.from_version}_{datetime.now():%Y%m%d_%H%M%S}"
+        )
+        backup_subdir.mkdir(parents=True, exist_ok=True)
+
+        # Backup all docs
+        docs_dir = htmlgraph_dir / "docs"
+        if docs_dir.exists():
+            for doc_file in docs_dir.glob("*.md"):
+                shutil.copy2(doc_file, backup_subdir / doc_file.name)
+
+        # Also backup root-level docs (legacy)
+        for doc_file in htmlgraph_dir.glob("*.md"):
+            shutil.copy2(doc_file, backup_subdir / doc_file.name)
+
+        return backup_subdir
+
+
+class V1toV2Migration(MigrationScript):
+    """Migrate from v1 (root-level docs) to v2 (template-based docs)."""
+
+    from_version = 1
+    to_version = 2
+
+    def migrate(self, htmlgraph_dir: Path, backup_dir: Path) -> bool:
+        """Migrate v1 docs to v2 template structure.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            True if migration successful
+        """
+        # Backup first
+        backup_path = self.backup_docs(htmlgraph_dir, backup_dir)
+        print(f"✅ Backed up to {backup_path}")
+
+        # Detect user customizations in old AGENTS.md
+        customizations = self._detect_customizations(htmlgraph_dir / "AGENTS.md")
+        if customizations:
+            print(f"📝 Detected customizations: {', '.join(customizations)}")
+
+        # Move old docs to archive
+        old_agents_md = htmlgraph_dir / "AGENTS.md"
+        if old_agents_md.exists():
+            old_agents_md.rename(htmlgraph_dir / "AGENTS.md.v1.backup")
+            print("📦 Archived old AGENTS.md")
+
+        # Generate new v2 docs with customizations preserved
+        self._generate_v2_docs(htmlgraph_dir, customizations)
+        print("✨ Generated v2 documentation")
+
+        # Update metadata
+        metadata = DocsMetadata.load(htmlgraph_dir)
+        metadata.schema_version = 2
+        metadata.customizations = customizations
+        metadata.save(htmlgraph_dir)
+        print("💾 Updated metadata")
+
+        return True
+
+    def _detect_customizations(self, agents_md_path: Path) -> list[str]:
+        """Detect user-customized sections in old AGENTS.md.
+
+        Args:
+            agents_md_path: Path to AGENTS.md file
+
+        Returns:
+            List of customized section names
+        """
+        if not agents_md_path.exists():
+            return []
+
+        content = agents_md_path.read_text()
+        customizations = []
+
+        # Simple heuristic: sections not in base template
+        if "## Our Team" in content:
+            customizations.append("custom_workflows")
+        if "## Project Conventions" in content:
+            customizations.append("project_conventions")
+        if "## Custom Workflows" in content:
+            customizations.append("custom_workflows")
+
+        return customizations
+
+    def _generate_v2_docs(self, htmlgraph_dir: Path, customizations: list[str]) -> None:
+        """Generate v2 template-based docs with customizations.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            customizations: List of customized sections to preserve
+        """
+        # NOTE: This would integrate with sync_docs.py
+        # For now, just create placeholder
+        docs_dir = htmlgraph_dir / "docs"
+        docs_dir.mkdir(exist_ok=True)
+
+        placeholder = docs_dir / "AGENTS.md"
+        placeholder.write_text(
+            """# HtmlGraph Agent Documentation (v2)
+
+This file was migrated from v1 to v2.
+
+Run `uv run htmlgraph sync-docs` to regenerate from templates.
+"""
+        )
+
+        # Inject customizations as template overrides if needed
+        if customizations:
+            self._create_override_template(htmlgraph_dir, customizations)
+
+    def _create_override_template(
+        self, htmlgraph_dir: Path, customizations: list[str]
+    ) -> None:
+        """Create template overrides for customizations.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            customizations: List of customizations to preserve
+        """
+        overrides_file = htmlgraph_dir / "docs" / "overrides.md"
+        overrides_file.write_text(
+            f"""# Documentation Customizations
+
+The following sections were customized in v1:
+
+{chr(10).join(f"- {c}" for c in customizations)}
+
+To preserve these customizations, add them back manually after running sync-docs.
+"""
+        )
+
+    def rollback(self, htmlgraph_dir: Path, backup_dir: Path) -> None:
+        """Rollback to v1 docs from backup.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+        """
+        # Find latest backup
+        backups = sorted(backup_dir.glob("v1_*"))
+        if not backups:
+            raise ValueError("No backup found for rollback")
+
+        latest_backup = backups[-1]
+        print(f"🔄 Rolling back from {latest_backup}")
+
+        # Restore old AGENTS.md
+        backup_agents = latest_backup / "AGENTS.md"
+        if backup_agents.exists():
+            shutil.copy2(backup_agents, htmlgraph_dir / "AGENTS.md")
+            print("✅ Restored AGENTS.md")
+
+        # Update metadata
+        metadata = DocsMetadata.load(htmlgraph_dir)
+        metadata.schema_version = 1
+        metadata.save(htmlgraph_dir)
+        print("💾 Updated metadata to v1")
+
+
+# Migration registry
+MIGRATIONS: dict[tuple[int, int], MigrationScript] = {
+    (1, 2): V1toV2Migration(),
+}
+
+
+def get_migration(from_version: int, to_version: int) -> MigrationScript | None:
+    """Get migration script for version transition.
+
+    Args:
+        from_version: Source schema version
+        to_version: Target schema version
+
+    Returns:
+        MigrationScript instance or None if no migration exists
+    """
+    return MIGRATIONS.get((from_version, to_version))

htmlgraph/docs/template_engine.py

@@ -0,0 +1,143 @@
+"""Jinja2-based template engine for documentation with user customization."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader
+
+
+class DocTemplateEngine:
+    """Renders documentation templates with user customization support.
+
+    Template Priority:
+    1. User templates in .htmlgraph/docs/templates/ (highest priority)
+    2. Package templates in htmlgraph/docs/templates/ (fallback)
+
+    Example:
+        >>> engine = DocTemplateEngine(Path(".htmlgraph"))
+        >>> content = engine.render_agents_md("0.21.0", "claude")
+        >>> print(content)
+    """
+
+    def __init__(self, htmlgraph_dir: Path):
+        """Initialize template engine with multi-loader.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+        """
+        # Package templates (bundled with pip install)
+        package_templates = Path(__file__).parent / "templates"
+
+        # User templates (project-specific customizations)
+        user_templates = htmlgraph_dir / "docs" / "templates"
+
+        # Multi-loader: User templates have priority over package templates
+        loaders = []
+        if user_templates.exists():
+            loaders.append(FileSystemLoader(str(user_templates)))
+        loaders.append(FileSystemLoader(str(package_templates)))
+
+        self.env = Environment(loader=ChoiceLoader(loaders))
+
+        # Add custom filters
+        self.env.filters["format_date"] = self._format_date
+        self.env.filters["highlight_code"] = self._highlight_code
+
+    def render(self, template_name: str, context: dict[str, Any]) -> str:
+        """Render template with context, merging user overrides.
+
+        Args:
+            template_name: Name of template file (e.g., "agents.md.j2")
+            context: Template variables
+
+        Returns:
+            Rendered content with user customizations applied
+
+        Example:
+            >>> engine.render("agents.md.j2", {"platform": "claude"})
+        """
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+
+    def render_agents_md(self, sdk_version: str, platform: str = "claude") -> str:
+        """Render AGENTS.md with platform-specific customizations.
+
+        Args:
+            sdk_version: HtmlGraph SDK version (e.g., "0.21.0")
+            platform: Platform name (claude, gemini, api, etc.)
+
+        Returns:
+            Rendered AGENTS.md content
+
+        Example:
+            >>> content = engine.render_agents_md("0.21.0", "claude")
+        """
+        context = {
+            "sdk_version": sdk_version,
+            "platform": platform,
+            "features_enabled": self._get_enabled_features(),
+            "custom_workflows": self._load_custom_workflows(),
+            "generated_at": datetime.now().isoformat(),
+        }
+        # User templates should extend "base_agents.md.j2" to avoid recursion
+        # Priority: agents.md.j2 (user override) → base_agents.md.j2 (package default)
+        template_name = "agents.md.j2"
+        try:
+            # Try to get user template first (will succeed if it exists in user dir)
+            self.env.get_template(template_name)
+            return self.render(template_name, context)
+        except:  # noqa
+            # Fall back to base template (always exists in package)
+            return self.render("base_agents.md.j2", context)
+
+    def _format_date(self, value: str) -> str:
+        """Format ISO date string for display.
+
+        Args:
+            value: ISO 8601 date string
+
+        Returns:
+            Formatted date string
+        """
+        try:
+            dt = datetime.fromisoformat(value)
+            return dt.strftime("%Y-%m-%d %H:%M")
+        except (ValueError, AttributeError):
+            return value
+
+    def _highlight_code(self, code: str, language: str = "python") -> str:
+        """Add markdown code fence with syntax highlighting.
+
+        Args:
+            code: Code snippet
+            language: Programming language for syntax highlighting
+
+        Returns:
+            Markdown code block
+        """
+        return f"```{language}\n{code}\n```"
+
+    def _get_enabled_features(self) -> dict[str, bool]:
+        """Get enabled features for this installation.
+
+        Returns:
+            Dictionary of feature flags
+        """
+        # TODO: Read from config or detect dynamically
+        return {
+            "sessions": True,
+            "tracks": True,
+            "analytics": True,
+            "mcp": True,
+            "cli": True,
+        }
+
+    def _load_custom_workflows(self) -> str | None:
+        """Load custom workflows from user template.
+
+        Returns:
+            Custom workflow markdown or None
+        """
+        # TODO: Load from .htmlgraph/docs/workflows.md if exists
+        return None

htmlgraph/docs/templates/_sections/cli_reference.md.j2

@@ -0,0 +1,52 @@
+## CLI Reference
+
+### Installation
+
+```bash
+pip install htmlgraph
+```
+
+### Basic Commands
+
+```bash
+# Initialize project
+htmlgraph init
+
+# Create work items
+htmlgraph feature create "Add authentication"
+htmlgraph bug create "Fix login redirect"
+htmlgraph spike create "Research OAuth providers"
+
+# List work items
+htmlgraph feature list
+htmlgraph status
+
+# Start MCP server
+htmlgraph mcp
+```
+
+### Session Management
+
+```bash
+# List sessions
+htmlgraph session list
+
+# Show active sessions
+htmlgraph session list --active
+
+# Link session to work item
+htmlgraph session link <session-id> <feature-id>
+```
+
+### Documentation
+
+```bash
+# Generate documentation
+htmlgraph docs generate --platform {{ platform }}
+
+# Sync documentation files
+htmlgraph sync-docs
+
+# Validate documentation
+htmlgraph docs validate
+```

htmlgraph/docs/templates/_sections/core_concepts.md.j2

@@ -0,0 +1,29 @@
+## Core Concepts
+
+### Graph Structure
+
+HtmlGraph uses HTML files as graph nodes and hyperlinks as edges:
+
+- **Nodes**: HTML files with `data-*` attributes
+- **Edges**: `<a href>` links between files
+- **Properties**: `data-*` attributes on elements
+- **Query Language**: CSS selectors
+
+### Work Item Types
+
+HtmlGraph supports multiple work item types:
+
+1. **Features** - New capabilities or enhancements
+2. **Bugs** - Issues to fix
+3. **Spikes** - Research or investigation tasks
+4. **Chores** - Maintenance and refactoring
+5. **Tracks** - Multi-feature initiatives
+
+### Session Tracking
+
+HtmlGraph automatically tracks agent sessions via git hooks:
+
+- Session start/end detection
+- Work item linking
+- Event logging
+- Transcript capture

htmlgraph/docs/templates/_sections/sdk_basics.md.j2

@@ -0,0 +1,69 @@
+## SDK Reference
+
+### SDK Initialization
+
+```python
+from htmlgraph import SDK
+
+# Initialize with agent name
+sdk = SDK(agent="{{ platform }}")
+
+# Access collections
+features = sdk.features
+bugs = sdk.bugs
+spikes = sdk.spikes
+tracks = sdk.tracks
+sessions = sdk.sessions
+```
+
+### Features API
+
+```python
+# Create feature
+feature = sdk.features.create("Add authentication") \
+    .set_priority("high") \
+    .set_status("in-progress") \
+    .add_steps([
+        "Setup OAuth provider",
+        "Implement JWT tokens",
+        "Add session management"
+    ]) \
+    .save()
+
+# Update feature
+feature = sdk.features.get(feature.id) \
+    .complete_step(0) \
+    .save()
+
+# List features
+all_features = sdk.features.list()
+high_priority = sdk.features.filter(priority="high")
+in_progress = sdk.features.filter(status="in-progress")
+```
+
+### Tracks API
+
+```python
+# Create track
+track = sdk.tracks.create("Authentication System") \
+    .set_priority("high") \
+    .add_feature(feature.id) \
+    .save()
+
+# Get track progress
+progress = track.get_progress()
+print(f"Completion: {progress['completion_percentage']}%")
+```
+
+### Analytics
+
+```python
+# Get strategic recommendations
+next_work = sdk.analytics.recommend_next_work(limit=5)
+
+# Find bottlenecks
+bottlenecks = sdk.analytics.find_bottlenecks()
+
+# Get summary
+summary = sdk.summary()
+```

htmlgraph/docs/templates/base_agents.md.j2

@@ -0,0 +1,78 @@
+{# Base template for AGENTS.md - Package provides this #}
+---
+version: "{{ sdk_version }}"
+platform: "{{ platform }}"
+generated: "{{ generated_at }}"
+---
+
+{% block header %}
+# HtmlGraph Agent Documentation
+{% endblock %}
+
+{% block introduction %}
+## Introduction
+
+HtmlGraph is a lightweight graph database framework built entirely on web standards (HTML, CSS, JavaScript) for AI agent coordination and human observability.
+
+**Tagline**: "HTML is All You Need"
+{% endblock %}
+
+{% block quick_start %}
+## Quick Start
+
+```python
+from htmlgraph import SDK
+
+# Initialize SDK for your agent
+sdk = SDK(agent="{{ platform }}")
+
+# Create a feature
+feature = sdk.features.create("Add authentication") \
+    .set_priority("high") \
+    .add_steps(["Setup OAuth", "Add JWT", "Test login"]) \
+    .save()
+
+# Track progress
+sdk.features.get(feature.id).complete_step(0).save()
+```
+{% endblock %}
+
+{% block core_concepts %}
+{% include "_sections/core_concepts.md.j2" %}
+{% endblock %}
+
+{% block sdk_reference %}
+{% include "_sections/sdk_basics.md.j2" %}
+{% endblock %}
+
+{% block cli_reference %}
+{% include "_sections/cli_reference.md.j2" %}
+{% endblock %}
+
+{% block custom_workflows %}
+{# Users can override this block in .htmlgraph/docs/templates/agents.md.j2 #}
+{% if custom_workflows %}
+## Custom Workflows
+
+{{ custom_workflows }}
+{% endif %}
+{% endblock %}
+
+{% block deployment %}
+## Deployment
+
+For deployment instructions, see the deployment guide:
+
+```bash
+# Build and publish package
+./scripts/deploy-all.sh 0.21.0 --no-confirm
+
+# Documentation changes only
+./scripts/deploy-all.sh --docs-only
+```
+{% endblock %}
+
+{% block footer %}
+---
+*Generated by HtmlGraph v{{ sdk_version }} on {{ generated_at }}*
+{% endblock %}