htmlgraph 0.2.0__tar.gz → 0.2.2__tar.gz

{htmlgraph-0.2.0 → htmlgraph-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.2.0
+Version: 0.2.2
 Summary: HTML is All You Need - Graph database on web standards
 Project-URL: Homepage, https://github.com/Shakes-tzd/htmlgraph
 Project-URL: Documentation, https://github.com/Shakes-tzd/htmlgraph#readme
@@ -209,6 +209,38 @@ HtmlGraph nodes are standard HTML files:
 3. **Documentation** - Interconnected docs with search
 4. **Task Management** - Todo lists with dependencies
 
+## Contributing
+
+HtmlGraph is developed using HtmlGraph itself (dogfooding). This means:
+
+- ✅ Every development action is replicable by users through the package
+- ✅ We use the SDK, CLI, and plugins - not custom scripts
+- ✅ Our development workflow IS the documentation
+
+**See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for:**
+- Dogfooding principles
+- Replicable workflows
+- Environment setup (PyPI tokens, etc.)
+- Development best practices
+
+**Quick start for contributors:**
+```bash
+# Clone and setup
+git clone https://github.com/Shakes-tzd/htmlgraph
+cd htmlgraph
+uv sync
+
+# Start tracking your work (dogfooding!)
+uv run htmlgraph init --install-hooks
+uv run htmlgraph serve  # View dashboard
+
+# Use SDK for development
+uv run python
+>>> from htmlgraph import SDK
+>>> sdk = SDK(agent="your-name")
+>>> sdk.features.where(status="todo")
+```
+
 ## License
 
 MIT
@@ -216,5 +248,6 @@ MIT
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)
-- [Documentation](https://github.com/Shakes-tzd/htmlgraph#readme)
-- [Examples](https://github.com/Shakes-tzd/htmlgraph/tree/main/examples)
+- [Documentation](docs/) - SDK guide, workflows, development principles
+- [Examples](examples/) - Real-world usage examples
+- [PyPI](https://pypi.org/project/htmlgraph/)

{htmlgraph-0.2.0 → htmlgraph-0.2.2}/README.md

@@ -175,6 +175,38 @@ HtmlGraph nodes are standard HTML files:
 3. **Documentation** - Interconnected docs with search
 4. **Task Management** - Todo lists with dependencies
 
+## Contributing
+
+HtmlGraph is developed using HtmlGraph itself (dogfooding). This means:
+
+- ✅ Every development action is replicable by users through the package
+- ✅ We use the SDK, CLI, and plugins - not custom scripts
+- ✅ Our development workflow IS the documentation
+
+**See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for:**
+- Dogfooding principles
+- Replicable workflows
+- Environment setup (PyPI tokens, etc.)
+- Development best practices
+
+**Quick start for contributors:**
+```bash
+# Clone and setup
+git clone https://github.com/Shakes-tzd/htmlgraph
+cd htmlgraph
+uv sync
+
+# Start tracking your work (dogfooding!)
+uv run htmlgraph init --install-hooks
+uv run htmlgraph serve  # View dashboard
+
+# Use SDK for development
+uv run python
+>>> from htmlgraph import SDK
+>>> sdk = SDK(agent="your-name")
+>>> sdk.features.where(status="todo")
+```
+
 ## License
 
 MIT
@@ -182,5 +214,6 @@ MIT
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)
-- [Documentation](https://github.com/Shakes-tzd/htmlgraph#readme)
-- [Examples](https://github.com/Shakes-tzd/htmlgraph/tree/main/examples)
+- [Documentation](docs/) - SDK guide, workflows, development principles
+- [Examples](examples/) - Real-world usage examples
+- [PyPI](https://pypi.org/project/htmlgraph/)

{htmlgraph-0.2.0 → htmlgraph-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlgraph"
-version = "0.2.0"
+version = "0.2.2"
 description = "HTML is All You Need - Graph database on web standards"
 authors = [{name = "Shakes", email = "shakestzd@gmail.com"}]
 readme = "README.md"

{htmlgraph-0.2.0 → htmlgraph-0.2.2}/src/python/htmlgraph/cli.py

@@ -236,6 +236,75 @@ fi
 
 printf "%s" "$UPDATES" | htmlgraph git-event push "$REMOTE_NAME" "$REMOTE_URL" &> /dev/null &
 exit 0
+"""
+
+    pre_commit = """#!/bin/bash
+#
+# HtmlGraph Pre-Commit Hook
+# Reminds developers to create/start features for non-trivial work
+#
+# To disable: git config htmlgraph.precommit false
+# To bypass once: git commit --no-verify
+
+# Check if hook is disabled via config
+if [ "$(git config --type=bool htmlgraph.precommit)" = "false" ]; then
+    exit 0
+fi
+
+# Check if HtmlGraph is initialized
+if [ ! -d ".htmlgraph" ]; then
+    # Not an HtmlGraph project, skip silently
+    exit 0
+fi
+
+# Fast check for in-progress features using grep (avoids Python startup)
+# This is 10-100x faster than calling the CLI
+ACTIVE_COUNT=$(find .htmlgraph/features -name "*.html" -exec grep -l 'data-status="in-progress"' {} \\; 2>/dev/null | wc -l | tr -d ' ')
+
+# If we have active features and htmlgraph CLI is available, get details
+if [ "$ACTIVE_COUNT" -gt 0 ] && command -v htmlgraph &> /dev/null; then
+    ACTIVE_FEATURES=$(htmlgraph feature list --status in-progress 2>/dev/null)
+else
+    ACTIVE_FEATURES=""
+fi
+
+# Redirect output to stderr (standard for git hooks)
+exec 1>&2
+
+if [ "$ACTIVE_COUNT" -gt 0 ]; then
+    # Active features exist - show them
+    echo ""
+    echo "✓ HtmlGraph: $ACTIVE_COUNT active feature(s)"
+    echo ""
+    echo "$ACTIVE_FEATURES"
+    echo ""
+else
+    # No active features - show reminder
+    echo ""
+    echo "⚠️  HtmlGraph Feature Reminder"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "No active features found. Did you forget to start one?"
+    echo ""
+    echo "For non-trivial work, consider:"
+    echo "  1. Create feature: (use Python API or dashboard)"
+    echo "  2. Start feature: htmlgraph feature start <feature-id>"
+    echo ""
+    echo "Quick decision:"
+    echo "  • >30 min work? → Create feature"
+    echo "  • 3+ files? → Create feature"
+    echo "  • Needs tests? → Create feature"
+    echo "  • Simple fix? → Direct commit OK"
+    echo ""
+    echo "To disable this reminder: git config htmlgraph.precommit false"
+    echo "To bypass once: git commit --no-verify"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Proceeding with commit..."
+    echo ""
+fi
+
+# Always exit 0 (allow commit)
+exit 0
 """
 
     def ensure_hook_file(hook_name: str, hook_content: str) -> Path:
@@ -249,6 +318,7 @@ exit 0
         return hook_dest
 
     hook_files = {
+        "pre-commit": ensure_hook_file("pre-commit", pre_commit),
         "post-commit": ensure_hook_file("post-commit", post_commit),
         "post-checkout": ensure_hook_file("post-checkout", post_checkout),
         "post-merge": ensure_hook_file("post-merge", post_merge),
@@ -325,6 +395,7 @@ fi
                 print(f"\n✓ Git hooks installed")
                 print(f"  {hook_name}: {git_hook_path}")
 
+        install_hook("pre-commit", hook_files["pre-commit"], pre_commit)
         install_hook("post-commit", hook_files["post-commit"], post_commit)
         install_hook("post-checkout", hook_files["post-checkout"], post_checkout)
         install_hook("post-merge", hook_files["post-merge"], post_merge)
@@ -1609,6 +1680,22 @@ curl Examples:
     mcp_serve.add_argument("--graph-dir", "-g", default=".htmlgraph", help="Graph directory")
     mcp_serve.add_argument("--agent", default="mcp", help="Agent name for session attribution")
 
+    # setup
+    setup_parser = subparsers.add_parser("setup", help="Set up HtmlGraph for AI CLI platforms")
+    setup_subparsers = setup_parser.add_subparsers(dest="setup_command", help="Platform to set up")
+
+    setup_claude = setup_subparsers.add_parser("claude", help="Set up for Claude Code")
+    setup_claude.add_argument("--auto-install", action="store_true", help="Automatically install when possible")
+
+    setup_codex = setup_subparsers.add_parser("codex", help="Set up for Codex CLI")
+    setup_codex.add_argument("--auto-install", action="store_true", help="Automatically install when possible")
+
+    setup_gemini = setup_subparsers.add_parser("gemini", help="Set up for Gemini CLI")
+    setup_gemini.add_argument("--auto-install", action="store_true", help="Automatically install when possible")
+
+    setup_all_parser = setup_subparsers.add_parser("all", help="Set up for all supported platforms")
+    setup_all_parser.add_argument("--auto-install", action="store_true", help="Automatically install when possible")
+
     args = parser.parse_args()
 
     if args.command == "serve":
@@ -1694,6 +1781,20 @@ curl Examples:
         else:
             mcp_parser.print_help()
             sys.exit(1)
+    elif args.command == "setup":
+        from htmlgraph.setup import setup_claude, setup_codex, setup_gemini, setup_all
+
+        if args.setup_command == "claude":
+            setup_claude(args)
+        elif args.setup_command == "codex":
+            setup_codex(args)
+        elif args.setup_command == "gemini":
+            setup_gemini(args)
+        elif args.setup_command == "all":
+            setup_all(args)
+        else:
+            setup_parser.print_help()
+            sys.exit(1)
     else:
         parser.print_help()
         sys.exit(1)

htmlgraph-0.2.2/src/python/htmlgraph/setup.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+HtmlGraph CLI Setup Commands
+
+Automates setup of HtmlGraph for different AI CLI platforms:
+- Claude Code (plugin via marketplace)
+- Codex CLI (skill installation)
+- Gemini CLI (extension installation)
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def check_command_exists(command: str) -> bool:
+    """Check if a command exists in PATH."""
+    return shutil.which(command) is not None
+
+
+def run_command(cmd: list[str], capture=False, check=True) -> subprocess.CompletedProcess:
+    """Run a shell command."""
+    try:
+        if capture:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=check)
+        else:
+            result = subprocess.run(cmd, check=check)
+        return result
+    except subprocess.CalledProcessError as e:
+        print(f"Error running command: {' '.join(cmd)}")
+        print(f"Exit code: {e.returncode}")
+        if capture and e.stderr:
+            print(f"Error: {e.stderr}")
+        raise
+
+
+def setup_claude(args):
+    """Set up HtmlGraph for Claude Code."""
+    print("🔧 Setting up HtmlGraph for Claude Code...")
+    print()
+
+    # Check if claude CLI exists
+    if not check_command_exists("claude"):
+        print("❌ Claude Code CLI not found")
+        print("   Install from: https://claude.com/download")
+        return False
+
+    print("✅ Claude Code CLI found")
+
+    # Check if marketplace is configured
+    print("\n📦 Checking marketplace configuration...")
+
+    # Get project root (where .htmlgraph might be)
+    project_root = Path.cwd()
+    marketplace_file = project_root / ".claude-plugin" / "marketplace.json"
+
+    if marketplace_file.exists():
+        print(f"✅ Marketplace configured at {marketplace_file}")
+    else:
+        print("⚠️  No local marketplace found")
+        print("   If you're developing HtmlGraph, you should be in the repo root")
+        print("   Otherwise, the plugin is available from the official marketplace")
+
+    # Check if plugin is installed
+    print("\n📋 Checking installed plugins...")
+    try:
+        result = run_command(["claude", "plugin", "list"], capture=True)
+        if "htmlgraph" in result.stdout:
+            print("✅ HtmlGraph plugin already installed")
+
+            # Try to get version
+            if "@" in result.stdout:
+                version_line = [line for line in result.stdout.split("\n") if "htmlgraph" in line]
+                if version_line:
+                    print(f"   {version_line[0].strip()}")
+        else:
+            print("⚠️  HtmlGraph plugin not installed")
+            print("\n📥 Install the plugin:")
+
+            if marketplace_file.exists():
+                print("   From local marketplace:")
+                print("   1. /plugin marketplace add .")
+                print("   2. /plugin install htmlgraph@htmlgraph-dev")
+            else:
+                print("   From official marketplace:")
+                print("   /plugin install htmlgraph")
+    except Exception as e:
+        print(f"⚠️  Could not check plugins: {e}")
+
+    print("\n✅ Claude Code setup complete!")
+    print("\n📚 Next steps:")
+    print("   1. Restart Claude Code if plugin was just installed")
+    print("   2. Run: htmlgraph init --install-hooks")
+    print("   3. Start coding - tracking is automatic!")
+    return True
+
+
+def setup_codex(args):
+    """Set up HtmlGraph for Codex CLI."""
+    print("🔧 Setting up HtmlGraph for Codex CLI...")
+    print()
+
+    # Check if codex CLI exists
+    if not check_command_exists("codex"):
+        print("❌ Codex CLI not found")
+        print("   Install with: npm install -g @openai/codex")
+        return False
+
+    print("✅ Codex CLI found")
+
+    # Check if skills are enabled
+    print("\n🎯 Checking if skills are enabled...")
+    print("   Run: codex --enable skills")
+    print("   (This only needs to be done once)")
+
+    # Find or create skills directory
+    home = Path.home()
+    codex_dir = home / ".codex"
+    skills_dir = codex_dir / "skills"
+    htmlgraph_skill_dir = skills_dir / "htmlgraph-tracker"
+
+    print(f"\n📁 Skills directory: {skills_dir}")
+
+    if not skills_dir.exists():
+        print("⚠️  Skills directory doesn't exist yet")
+        print("   It will be created when you enable skills")
+    else:
+        print("✅ Skills directory exists")
+
+    # Check if skill is already installed
+    if htmlgraph_skill_dir.exists():
+        print(f"\n✅ HtmlGraph skill already installed at {htmlgraph_skill_dir}")
+
+        # Check if SKILL.md exists
+        skill_md = htmlgraph_skill_dir / "SKILL.md"
+        if skill_md.exists():
+            print("✅ SKILL.md found")
+        else:
+            print("⚠️  SKILL.md not found - skill may be incomplete")
+    else:
+        print(f"\n⚠️  HtmlGraph skill not installed")
+        print("\n📥 Installation options:")
+
+        # Check if we're in the HtmlGraph repo
+        repo_skill = Path.cwd() / "packages" / "codex-skill"
+        if repo_skill.exists():
+            print("\n   Option 1: Link from this repo (recommended for development):")
+            print(f"   ln -s {repo_skill.absolute()} {htmlgraph_skill_dir}")
+
+            if args.auto_install:
+                print("\n   Auto-installing...")
+                skills_dir.mkdir(parents=True, exist_ok=True)
+                try:
+                    if htmlgraph_skill_dir.exists():
+                        htmlgraph_skill_dir.unlink()
+                    htmlgraph_skill_dir.symlink_to(repo_skill.absolute())
+                    print(f"   ✅ Skill linked to {htmlgraph_skill_dir}")
+                except Exception as e:
+                    print(f"   ❌ Failed to link skill: {e}")
+
+        print("\n   Option 2: Copy from GitHub:")
+        print("   git clone https://github.com/Shakes-tzd/htmlgraph.git")
+        print(f"   cp -r htmlgraph/packages/codex-skill {htmlgraph_skill_dir}")
+
+        print("\n   Option 3: Download manually:")
+        print("   https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/codex-skill")
+
+    # Check MCP configuration
+    print("\n🔌 Checking MCP configuration...")
+    codex_config = codex_dir / "config.toml"
+
+    if codex_config.exists():
+        print(f"✅ Codex config found at {codex_config}")
+        print("   MCP servers can be configured in this file")
+        print("   Run: codex mcp serve")
+    else:
+        print("⚠️  No Codex config found yet")
+        print("   It will be created when you run Codex for the first time")
+
+    print("\n✅ Codex CLI setup complete!")
+    print("\n📚 Next steps:")
+    print("   1. Enable skills: codex --enable skills")
+    print("   2. Install the skill (see options above)")
+    print("   3. Run: htmlgraph init --install-hooks")
+    print("   4. Start Codex - skill will auto-activate!")
+    return True
+
+
+def setup_gemini(args):
+    """Set up HtmlGraph for Gemini CLI."""
+    print("🔧 Setting up HtmlGraph for Gemini CLI...")
+    print()
+
+    # Check if gemini CLI exists
+    if not check_command_exists("gemini"):
+        print("❌ Gemini CLI not found")
+        print("   Install with: npm install -g @google/generative-ai-cli")
+        return False
+
+    print("✅ Gemini CLI found")
+
+    # Check for extensions
+    print("\n🎯 Checking for HtmlGraph extension...")
+
+    try:
+        result = run_command(["gemini", "extensions", "list"], capture=True, check=False)
+        if result.returncode == 0 and "htmlgraph" in result.stdout.lower():
+            print("✅ HtmlGraph extension already installed")
+        else:
+            print("⚠️  HtmlGraph extension not installed")
+            print("\n📥 Installation options:")
+
+            # Check if we're in the HtmlGraph repo
+            repo_extension = Path.cwd() / "packages" / "gemini-extension"
+            if repo_extension.exists():
+                print(f"\n   Option 1: Install from this repo:")
+                print(f"   gemini extensions install {repo_extension.absolute()}")
+
+                if args.auto_install:
+                    print("\n   Auto-installing...")
+                    try:
+                        run_command(["gemini", "extensions", "install", str(repo_extension.absolute())])
+                        print("   ✅ Extension installed")
+                    except Exception as e:
+                        print(f"   ❌ Failed to install extension: {e}")
+
+            print("\n   Option 2: Install from GitHub:")
+            print("   gemini extensions install https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/gemini-extension")
+
+            print("\n   Option 3: Create manually:")
+            print("   gemini extensions create htmlgraph-tracker")
+    except Exception as e:
+        print(f"⚠️  Could not check extensions: {e}")
+
+    # Check hooks capability
+    print("\n🎉 Good news: Gemini CLI supports hooks!")
+    print("   The HtmlGraph extension includes automatic session tracking:")
+    print("   - SessionStart hook → Auto-start session")
+    print("   - AfterTool hook → Track all tool usage")
+    print("   - SessionEnd hook → Auto-finalize session")
+    print("   Just like Claude Code - no manual session management needed!")
+
+    print("\n✅ Gemini CLI setup complete!")
+    print("\n📚 Next steps:")
+    print("   1. Install the extension (see options above)")
+    print("   2. Run: htmlgraph init --install-hooks")
+    print("   3. Start Gemini - tracking is automatic!")
+    return True
+
+
+def setup_all(args):
+    """Set up HtmlGraph for all supported platforms."""
+    print("🚀 Setting up HtmlGraph for all supported platforms...")
+    print("=" * 60)
+    print()
+
+    results = {}
+
+    # Claude Code
+    print("1️⃣  CLAUDE CODE")
+    print("-" * 60)
+    results["claude"] = setup_claude(args)
+    print()
+    print()
+
+    # Codex CLI
+    print("2️⃣  CODEX CLI")
+    print("-" * 60)
+    results["codex"] = setup_codex(args)
+    print()
+    print()
+
+    # Gemini CLI
+    print("3️⃣  GEMINI CLI")
+    print("-" * 60)
+    results["gemini"] = setup_gemini(args)
+    print()
+    print()
+
+    # Summary
+    print("=" * 60)
+    print("📊 SETUP SUMMARY")
+    print("=" * 60)
+    for platform, success in results.items():
+        status = "✅" if success else "⚠️ "
+        print(f"{status} {platform.upper()}: {'Ready' if success else 'Needs attention'}")
+    print()
+
+    return all(results.values())