ai-config-cli 0.1.0__tar.gz

ai_config_cli-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,82 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force
+
+  build-check:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Check build output
+        run: |
+          echo "Documentation builds successfully"
+          echo "Site size: $(du -sh site/ | cut -f1)"
+          echo "Pages built: $(find site/ -name "*.html" | wc -l)"

ai_config_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # Required for trusted publishing
+      contents: read    # Required for checkout
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No token needed with trusted publishing

ai_config_cli-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Code Quality Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run Linter
+        run: uv run ruff check src/
+
+      - name: Run Formatter Check
+        run: uv run ruff format --check src/
+
+      - name: Run Type Checker
+        run: uv run ty check src/
+
+      - name: Run Tests
+        run: uv run pytest tests/ --cov=src/ai_config --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        continue-on-error: true
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

ai_config_cli-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+eggs/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ty_cache/
+
+# Linting
+.ruff_cache/
+
+# Documentation
+site/
+.cache/
+
+# IDE
+.idea/
+.vs_code/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+
+# Packaging
+*.lock
+!uv.lock

ai_config_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+-   repo: local
+    hooks:
+    -   id: lint
+        name: Run Linter
+        entry: uv run ruff check src/
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: format
+        name: Run Formatter
+        entry: uv run ruff format --check src/
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: ty
+        name: Run Type Checker
+        entry: uv run ty check src/
+        language: system
+        always_run: true
+        pass_filenames: false
+    -   id: test
+        name: Run Tests
+        entry: uv run pytest tests/ -q
+        language: system
+        always_run: true
+        pass_filenames: false

ai_config_cli-0.1.0/AGENTS.md

@@ -0,0 +1,107 @@
+# ai-config
+
+Declarative plugin manager for Claude Code.
+
+## Why This Exists
+
+Claude Code plugins let you extend Claude with custom skills, hooks, and MCP servers. Managing them manually (`claude plugin install`, `claude plugin marketplace add`) doesn't scale across machines or teams.
+
+ai-config provides a YAML config file for declarative plugin management. Define what you want, run `ai-config sync`, done.
+
+## Repo Map
+
+```
+src/ai_config/
+├── cli.py           # Click CLI entry point
+├── config.py        # Config file parsing
+├── operations.py    # sync, update, status logic
+├── init.py          # Interactive setup wizard
+├── watch.py         # File watcher for dev mode
+├── adapters/        # Tool-specific adapters (claude.py)
+└── validators/      # Validation (plugins, skills, hooks, MCP)
+tests/
+├── unit/            # Fast unit tests
+└── integration/     # Integration tests (marked)
+```
+
+## How to Work Here
+
+1. **Setup**: `uv sync --all-extras`
+2. **Make changes**
+3. **Validate**: `uv run ruff check src/ && uv run ty check src/ && uv run pytest tests/unit/ -v`
+4. **Commit** when all checks pass
+
+## Commands
+
+All commands use `uv run` (or `just` if installed).
+
+| Task | Command |
+|------|---------|
+| Install deps | `uv sync --all-extras` |
+| Lint | `uv run ruff check src/` |
+| Format | `uv run ruff format src/` |
+| Fix lint | `uv run ruff check src/ --fix` |
+| Type check | `uv run ty check src/` |
+| All checks | `uv run ruff check src/ && uv run ty check src/ && uv run pytest tests/ -v` |
+| Unit tests | `uv run pytest tests/unit/ -v` |
+| Single test | `uv run pytest tests/unit/test_foo.py -v` |
+| Coverage | `uv run pytest tests/ -v --cov=src/ai_config --cov-report=term-missing` |
+| Docs serve | `uv run mkdocs serve` |
+
+If `just` is available, use `just check` (runs lint + ty + test).
+
+## Code Style
+
+Enforced by tooling—don't memorize rules, run the tools:
+
+- **Formatting**: `ruff format` (line-length 100)
+- **Linting**: `ruff check` with autofix
+- **Types**: `ty check` with strict mode
+
+Conventions:
+- Python 3.9+ syntax
+- Type annotations required
+- Imports: stdlib → third-party → local (enforced by ruff isort)
+
+## Testing
+
+- Unit tests in `tests/unit/` - fast, no external deps
+- Integration tests marked with `@pytest.mark.integration`
+- Run single test: `uv run pytest tests/unit/test_config.py::test_name -v`
+
+## Releases
+
+**Before merging a PR with user-facing changes:**
+1. Update `CHANGELOG.md` under `[Unreleased]` section
+2. Use Keep a Changelog format: Added, Changed, Deprecated, Removed, Fixed, Security
+
+**To release a new version:**
+1. Move `[Unreleased]` entries to new version section with date
+2. Update version in `pyproject.toml`
+3. Update comparison links at bottom of CHANGELOG.md
+4. Create PR, merge to main
+5. Create GitHub release with tag `vX.Y.Z` (this auto-publishes to PyPI)
+
+Version is in `pyproject.toml` (currently `0.1.0`). Tags use `v` prefix (e.g., `v0.1.0`).
+
+### PyPI Publishing
+
+Publishing is automated via GitHub Actions (`.github/workflows/publish.yml`):
+- Triggered when a GitHub Release is published
+- Uses trusted publishing (no API tokens needed)
+- Requires PyPI environment configured in repo settings
+
+**One-time setup (repo admin):**
+1. Go to PyPI → Account settings → Publishing
+2. Add trusted publisher: GitHub, `safurrier/ai-config`, workflow `publish.yml`, environment `pypi`
+3. Go to GitHub repo → Settings → Environments → Create `pypi` environment
+
+## Nested Docs
+
+- `src/AGENTS.md` - Code patterns, validator/CLI extension guides
+
+## Gotchas
+
+- **Claude Code reloads plugins at session start** - after `ai-config sync`, restart Claude Code (use `claude --resume` to continue)
+- **Config locations**: `.ai-config/config.yaml` (project) or `~/.ai-config/config.yaml` (global)
+- **Scopes**: `user` scope installs to `~/.claude/plugins/`, `project` scope to `.claude/plugins/`

ai_config_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-02-03
+
+### Added
+
+- Initial release
+- `init` command - interactive config generator
+- `sync` command - install/uninstall plugins to match config
+- `status` command - show current plugin state
+- `watch` command - auto-sync on file changes
+- `update` command - update plugins to latest versions
+- `doctor` command - validate setup with fix hints
+- `plugin create` command - scaffold new plugins
+- `cache clear` command - clear plugin cache
+- Support for GitHub and local marketplaces
+- User and project scope plugin installation
+
+[Unreleased]: https://github.com/safurrier/ai-config/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/safurrier/ai-config/releases/tag/v0.1.0

ai_config_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

ai_config_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to ai-config
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone git@github.com:your-username/ai-config.git`
+3. Create a new branch: `git checkout -b feature-name`
+4. Make your changes
+5. Run quality checks: `just check`
+6. Commit your changes: `git commit -m "Description of changes"`
+7. Push to your fork: `git push origin feature-name`
+8. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Install dependencies
+just setup
+
+# Run all quality checks (lint, type check, test)
+just check
+```
+
+## Code Quality Standards
+
+- All code must be typed with proper type hints
+- Tests must be included for new features
+- All quality checks must pass (`just check`)
+
+## Pull Request Process
+
+1. Update the README.md with details of significant changes
+2. Update the CHANGELOG.md following the existing format
+3. The PR will be merged once you have the sign-off of a maintainer
+
+## Questions?
+
+Feel free to open an issue for any questions or concerns.

ai_config_cli-0.1.0/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.

ai_config_cli-0.1.0/PKG-INFO

@@ -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