ai-config-cli 0.1.0__py3-none-any.whl

ai_config/watch.py

@@ -0,0 +1,279 @@
+"""File watching for auto-sync on changes."""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from threading import Event, Timer
+from typing import Literal
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+from ai_config.types import AIConfig, PluginSource
+
+
+@dataclass
+class FileChange:
+    """Represents a detected file change."""
+
+    path: Path
+    change_type: Literal["config", "plugin_directory"]
+    event_type: str  # "created", "modified", "deleted"
+
+
+@dataclass
+class WatchConfig:
+    """Configuration for file watching."""
+
+    config_path: Path
+    plugin_directories: list[Path]
+    debounce_seconds: float = 1.5
+
+
+# Patterns to ignore when watching files
+IGNORE_PATTERNS = frozenset(
+    {
+        ".swp",  # Vim swap files
+        ".swo",  # Vim swap overflow
+        ".swn",  # Vim swap
+        "~",  # Backup files
+        ".tmp",  # Temp files
+        ".bak",  # Backup files
+    }
+)
+
+IGNORE_DIRS = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        ".pytest_cache",
+        "node_modules",
+        ".venv",
+        "venv",
+    }
+)
+
+
+def collect_watch_paths(config: AIConfig, config_path: Path) -> WatchConfig:
+    """Extract paths to watch from config.
+
+    Args:
+        config: The loaded AIConfig.
+        config_path: Path to the config file itself.
+
+    Returns:
+        WatchConfig with paths to monitor.
+    """
+    plugin_directories: list[Path] = []
+
+    for target in config.targets:
+        if target.type == "claude":
+            for marketplace in target.config.marketplaces.values():
+                if marketplace.source == PluginSource.LOCAL:
+                    plugin_directories.append(Path(marketplace.path))
+
+    return WatchConfig(
+        config_path=config_path,
+        plugin_directories=plugin_directories,
+    )
+
+
+def _should_ignore_path(path: Path) -> bool:
+    """Check if a path should be ignored.
+
+    Args:
+        path: Path to check.
+
+    Returns:
+        True if the path should be ignored.
+    """
+    # Check file suffixes/patterns
+    name = path.name
+    for pattern in IGNORE_PATTERNS:
+        if name.endswith(pattern):
+            return True
+
+    # Check for hidden files starting with .
+    if name.startswith(".") and not name.startswith(".."):
+        # Allow normal dotfiles but check for swap pattern
+        if name.endswith(".swp") or name.endswith(".swo"):
+            return True
+
+    # Check if any parent is an ignored directory
+    for part in path.parts:
+        if part in IGNORE_DIRS:
+            return True
+
+    return False
+
+
+class ChangeCollector(FileSystemEventHandler):
+    """Collects file changes and debounces callback invocation."""
+
+    def __init__(
+        self,
+        config_path: Path,
+        plugin_directories: list[Path],
+        debounce_seconds: float,
+        on_changes: Callable[[list[FileChange]], None],
+    ) -> None:
+        """Initialize the collector.
+
+        Args:
+            config_path: Path to the config file.
+            plugin_directories: List of plugin directories to monitor.
+            debounce_seconds: Seconds to wait before firing callback.
+            on_changes: Callback to invoke with collected changes.
+        """
+        super().__init__()
+        self._config_path = config_path.resolve()
+        self._plugin_directories = [d.resolve() for d in plugin_directories]
+        self._debounce_seconds = debounce_seconds
+        self._on_changes = on_changes
+        self._pending_changes: dict[Path, FileChange] = {}
+        self._debounce_timer: Timer | None = None
+
+    def _classify_change(self, path: Path) -> Literal["config", "plugin_directory"] | None:
+        """Classify a file change by type.
+
+        Args:
+            path: Path of the changed file.
+
+        Returns:
+            Change type or None if not a watched path.
+        """
+        resolved = path.resolve()
+
+        if resolved == self._config_path:
+            return "config"
+
+        for plugin_dir in self._plugin_directories:
+            try:
+                resolved.relative_to(plugin_dir)
+                return "plugin_directory"
+            except ValueError:
+                continue
+
+        return None
+
+    def _handle_event(self, event: FileSystemEvent) -> None:
+        """Handle a file system event.
+
+        Args:
+            event: The watchdog event.
+        """
+        if event.is_directory:
+            return
+
+        src_path = event.src_path
+        if isinstance(src_path, bytes):
+            src_path = src_path.decode()
+        path = Path(src_path)
+
+        if _should_ignore_path(path):
+            return
+
+        change_type = self._classify_change(path)
+        if change_type is None:
+            return
+
+        # Add to pending changes (deduplicate by path)
+        self._pending_changes[path] = FileChange(
+            path=path,
+            change_type=change_type,
+            event_type=event.event_type,
+        )
+
+        # Reset debounce timer
+        if self._debounce_timer is not None:
+            self._debounce_timer.cancel()
+
+        self._debounce_timer = Timer(self._debounce_seconds, self._fire_callback)
+        self._debounce_timer.daemon = True
+        self._debounce_timer.start()
+
+    def _fire_callback(self) -> None:
+        """Fire the callback with collected changes."""
+        if not self._pending_changes:
+            return
+
+        changes = list(self._pending_changes.values())
+        self._pending_changes.clear()
+        self._debounce_timer = None
+
+        self._on_changes(changes)
+
+    def on_created(self, event: FileSystemEvent) -> None:
+        """Handle file created event."""
+        self._handle_event(event)
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        """Handle file modified event."""
+        self._handle_event(event)
+
+    def on_deleted(self, event: FileSystemEvent) -> None:
+        """Handle file deleted event."""
+        self._handle_event(event)
+
+    def on_moved(self, event: FileSystemEvent) -> None:
+        """Handle file moved event."""
+        self._handle_event(event)
+
+
+@dataclass
+class WatchResult:
+    """Result of a watch operation."""
+
+    config_changes: int = 0
+    plugin_changes: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+def run_watch_loop(
+    watch_config: WatchConfig,
+    on_changes: Callable[[list[FileChange]], None],
+    stop_event: Event,
+    debounce_seconds: float = 1.5,
+) -> None:
+    """Run the watch loop until stop_event is set.
+
+    Args:
+        watch_config: Configuration for what to watch.
+        on_changes: Callback to invoke when changes are detected.
+        stop_event: Event to signal the loop should stop.
+        debounce_seconds: Seconds to wait before syncing after changes.
+    """
+    collector = ChangeCollector(
+        config_path=watch_config.config_path,
+        plugin_directories=watch_config.plugin_directories,
+        debounce_seconds=debounce_seconds,
+        on_changes=on_changes,
+    )
+
+    observer = Observer()
+
+    # Watch config file's directory
+    if watch_config.config_path.parent.exists():
+        observer.schedule(
+            collector,
+            str(watch_config.config_path.parent),
+            recursive=False,
+        )
+
+    # Watch plugin directories recursively
+    for plugin_dir in watch_config.plugin_directories:
+        if plugin_dir.exists():
+            observer.schedule(
+                collector,
+                str(plugin_dir),
+                recursive=True,
+            )
+
+    observer.start()
+
+    try:
+        while not stop_event.is_set():
+            stop_event.wait(timeout=0.5)
+    finally:
+        observer.stop()
+        observer.join()

ai_config_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: ai-config-cli
+Version: 0.1.0
+Summary: Declarative plugin manager for Claude Code
+Project-URL: Homepage, https://github.com/safurrier/ai-config
+Project-URL: Documentation, https://safurrier.github.io/ai-config/
+Project-URL: Repository, https://github.com/safurrier/ai-config
+Project-URL: Issues, https://github.com/safurrier/ai-config/issues
+Project-URL: Changelog, https://github.com/safurrier/ai-config/blob/main/CHANGELOG.md
+Author-email: Alex Furrier <afurrier@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,claude-code,configuration,plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Requires-Dist: watchdog>=3.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: ty>=0.0.2; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Requires-Dist: types-requests>=2.28; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.6.14; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26.1; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# ai-config
+
+Declarative plugin manager for Claude Code.
+
+(Future: Codex CLI and OpenCode support planned once plugins become more standardized for sharing ai-context)
+
+## Why this exists
+
+Claude Code plugins are useful. They let you extend Claude with custom skills, hooks, and MCP servers. The problem is managing them.
+
+Without ai-config, you're running `claude plugin install` and `claude plugin marketplace add` commands by hand across machines. There's no config file. No way to version control your setup. No way to share it.
+
+ai-config fixes that. You write a YAML file describing what plugins you want, and it handles the rest.
+
+Or more simply, run `ai-config init` and it writes the config for you.
+
+## What this isn't
+
+This README does not have:
+
+- 14 shields.io badges declaring build status, coverage, npm downloads, discord members, twitter followers, and mass-to-charge ratio
+- A mass of emojis to make it look "friendly" and "approachable"
+- Claims about revolutionizing your development workflow
+- Integration with 47 different tools (we integrate with one)
+- A "Quick Start" that's actually 73 steps
+- Screenshots of a dashboard that doesn't exist
+- A "Powered by AI" badge despite just being a for-loop
+
+It's a config file and some commands. That's it.
+
+## Installation
+
+> **Alpha software**: This project is in active development. APIs and config formats may change between versions.
+
+```bash
+pip install ai-config-cli
+# or
+uv tool install ai-config-cli
+```
+
+This installs `ai-config` globally. Run `ai-config --help` to verify.
+
+### From source (latest)
+
+```bash
+uv tool install git+https://github.com/safurrier/ai-config
+```
+
+### For development
+
+```bash
+git clone https://github.com/safurrier/ai-config.git
+cd ai-config
+just setup    # Install dependencies
+just check    # Run lint, type check, tests
+```
+
+## Quick Start
+
+**1. Create your config**
+
+```bash
+ai-config init
+```
+
+Interactive wizard walks you through adding marketplaces and plugins. Creates `.ai-config/config.yaml`.
+
+**2. Sync to install plugins**
+
+```bash
+ai-config sync
+```
+
+Installs/uninstalls plugins to match your config. Run this after editing `config.yaml`.
+
+If plugins seem stale or out of date:
+
+```bash
+ai-config sync --fresh
+```
+
+**3. Iterate with watch (plugin development)**
+
+```bash
+ai-config watch
+```
+
+Auto-syncs when you edit config or plugin files. Press Ctrl+C to stop.
+
+**Note:** Claude Code loads plugins at session start. After changes sync, restart Claude Code to apply them. Use `claude --resume` to continue your previous session.
+
+**4. Troubleshoot with doctor**
+
+```bash
+ai-config doctor
+```
+
+Validates marketplaces, plugins, skills, hooks, and MCP servers. Shows fix hints for any issues.
+
+## What it does
+
+**Declarative config** - Define your plugins in `.ai-config/config.yaml`:
+
+```yaml
+version: 1
+targets:
+  - type: claude
+    config:
+      marketplaces:
+        claude-code-tutorial:
+          source: github
+          repo: safurrier/claude-code-tutorial
+      plugins:
+        - id: claude-code-tutorial@claude-code-tutorial
+          scope: user
+          enabled: true
+```
+
+**Interactive setup** - Don't want to write YAML? Run the wizard:
+
+```bash
+ai-config init
+```
+
+It walks you through adding marketplaces and plugins with arrow-key navigation.
+
+**Sync** - Make reality match your config:
+
+```bash
+ai-config sync
+```
+
+**Validation** - Find problems before they bite you:
+
+```bash
+ai-config doctor
+```
+
+Checks that marketplaces exist, plugins are installed, skills are valid, hooks work.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `init` | Interactive config generator |
+| `sync` | Install/uninstall plugins to match config |
+| `status` | Show what's currently installed |
+| `watch` | Auto-sync on file changes (plugin development) |
+| `update` | Update plugins to latest versions |
+| `doctor` | Validate setup and show fix hints |
+| `plugin create` | Scaffold a new plugin |
+| `cache clear` | Clear the plugin cache |
+
+## Config file locations
+
+ai-config looks for config in this order:
+
+1. `.ai-config/config.yaml` (project-local)
+2. `~/.ai-config/config.yaml` (global)
+
+You can also pass `-c /path/to/config.yaml` to any command.
+
+## Scopes
+
+Plugins can be installed in different scopes:
+
+- **user** - Available everywhere (`~/.claude/plugins/`)
+- **project** - Only in the current project (`.claude/plugins/`)
+
+## Troubleshooting
+
+**Plugin installed but not showing up in / commands**
+
+Clear cache and re-sync:
+
+```bash
+ai-config sync --fresh
+```
+
+**Something's broken and Claude Code won't help**
+
+```bash
+ai-config doctor --verbose
+```
+
+## License
+
+MIT

ai_config_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+ai_config/__init__.py,sha256=gjK4b53Q3FicdMkCfFxlMfb1UGppWUPA2eQlgPU4upU,88
+ai_config/__main__.py,sha256=GmxRKMTWWibho0WpkCjFMil8jZBSToDFf-Otenax0Xs,114
+ai_config/cli.py,sha256=aMt_h9B5GJSB08qvO_SkzC3V3-GzI1Y346-if3Z0cuE,23865
+ai_config/cli_render.py,sha256=gJ3Lnb-4_ONXNIz2sRjVDhdDGIi833WGC_WnTFX0xKQ,18658
+ai_config/cli_theme.py,sha256=AU3EdLAvyWtxwFtQYNhowRCBJerlZfU89cFgwDRq5wo,1094
+ai_config/config.py,sha256=mqol3YKXiipkBqdJV1cBBvlhMFu4PRjOsbw5ypiChZs,8686
+ai_config/init.py,sha256=uJl7Egh13iJlG6_ciuYIRbA3GwOa339bUp5NZO1BNjY,22517
+ai_config/operations.py,sha256=om967tGLhywcz_RFoDc0nXjzRp-O8NMmVffd32YWJj8,10907
+ai_config/scaffold.py,sha256=rP-U2rwEe67WXp26-9LzoalRP_S8MjntrXO5D7xONSw,1836
+ai_config/settings.py,sha256=uwqVpz_YkTqaFI8Qtq7UIWx7KF1l2Nd86CFD8P0B0As,1642
+ai_config/types.py,sha256=Rn9QNdWvymH28jLi_mLn_e_rnVKWoMxwZ7tgNWFKzdM,4022
+ai_config/watch.py,sha256=fYCZTc__jzEpj38633wF62wT7J5DFmYrid_n1h_7NlI,7711
+ai_config/adapters/__init__.py,sha256=qHNJ4e7OVzkreIS5Cu7KtehPVGiWmrWMPUqZ97NiKIM,46
+ai_config/adapters/claude.py,sha256=baWdzMFVj94mO10jUCm6AojcKxT5svqYtNh00ADPcYU,9496
+ai_config/validators/__init__.py,sha256=nCk8_PKQ1_RBd_CaWLB5BHEug_JOb3OlLJ3dyldfqEQ,4404
+ai_config/validators/base.py,sha256=AfOxBJOjVSrw8uHsUZTlz4ZdTGmtFvkxgOm77HXo8rI,1225
+ai_config/validators/context.py,sha256=q1IxgX501e3GoiLhJAxJYQQlOFlxlMKlSYmfNKJeKM8,2642
+ai_config/validators/component/__init__.py,sha256=nPod-3X9oLl1mUfz_kyfmUzIxogZTG2BWGpLhClmrFw,64
+ai_config/validators/component/hook.py,sha256=h7bCoQYD03WAsspNCIoX-iz5Mb7rxexjmc0kxnL0UT4,13188
+ai_config/validators/component/mcp.py,sha256=Oq9X-K9EDO4bTUGE70lEW4EIn30mUsq65Fi4L4Vhvaw,8613
+ai_config/validators/component/skill.py,sha256=o5uAaWVljpGEw0Xx85d7tovt7gYrRZ9AwK_w96PO-EM,12647
+ai_config/validators/marketplace/__init__.py,sha256=eg1JthnlrnEQeG8Daghyn4zZOKLea3y5xYuqfUxHv7M,44
+ai_config/validators/marketplace/validators.py,sha256=uOmO8yl4q10QvIt4kNhUyb4V3qWhhhqbI-WfxSkbDC4,16353
+ai_config/validators/plugin/__init__.py,sha256=xT8IoczuJrhorek6naYwZNESDaQkeOJ_nijozAOz4Wo,39
+ai_config/validators/plugin/validators.py,sha256=dP4T-JhuC41CDcllvgRwlVTkwHdKf106aR-bpk5pzFs,12170
+ai_config/validators/target/__init__.py,sha256=A_57pCwACG1oFd80UlGUN1iWRHlYqzceBz5aCYYtTKA,39
+ai_config/validators/target/claude.py,sha256=rYs9gqQRcqtnN-jv4EA5HXIrpIP-DEq6lVqAJGk9b78,5014
+ai_config_cli-0.1.0.dist-info/METADATA,sha256=YkMC1WvFkCl1YRPkVF6vKbdkHH_TLAZkZi6ji805Ql8,6603
+ai_config_cli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ai_config_cli-0.1.0.dist-info/entry_points.txt,sha256=Bw4iKZy9_HtrJplb26AWXbVOQYugpMre11wg31GhnB0,49
+ai_config_cli-0.1.0.dist-info/licenses/LICENSE,sha256=YubrN8gJ2atD-zJmLwr1OJa2pejx1ZwArylzHBEYAb8,1069
+ai_config_cli-0.1.0.dist-info/RECORD,,

ai_config_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_config_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ai-config = ai_config.cli:main

ai_config_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alex Furrier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.