ruff-sync 0.0.5.dev2__tar.gz → 0.1.0.dev1__tar.gz

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: mkdocs-generation
+description: Generate MkDocs documentation sites with Material theme, mkdocstrings for API docs, and versioning. Use when setting up or extending project documentation.
+---
+
+# MkDocs Documentation Generation
+
+Generate professional documentation sites using MkDocs Material theme with automatic API reference generation.
+
+## Stack
+
+- **MkDocs**: Static site generator for project documentation
+- **Material Theme**: Modern, responsive theme with navigation features
+- **mkdocstrings**: Auto-generate API docs from Python docstrings
+- **mike**: Version management for documentation
+
+## Dependencies
+
+Add to `pyproject.toml` (optional extras group):
+
+```toml
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.4",
+    "mkdocstrings[python]>=0.24",
+    "mike>=2.0",
+]
+```
+
+Or `requirements.txt`:
+
+```
+mkdocs>=1.5
+mkdocs-material>=9.4
+mkdocstrings[python]>=0.24
+mike>=2.0
+```
+
+## Directory Structure
+
+**Simple (flat)**:
+```
+docs/
+├── index.md           # Home/overview
+├── getting-started.md # Installation and quickstart
+├── configuration.md   # Config options
+└── tools.md          # Feature reference
+```
+
+**Complex (nested)**:
+```
+docs/
+├── index.md
+├── compatibility.md
+├── guide/
+│   ├── getting-started.md
+│   ├── cli.md
+│   └── advanced.md
+└── api/
+    ├── panel.md       # ::: module.Class
+    └── entities/
+        ├── area.md
+        └── zone.md
+```
+
+## mkdocs.yml Configuration
+
+See `templates/mkdocs.yml` for the full configuration template.
+
+Key sections:
+1. **Site metadata**: name, description, URLs
+2. **Versioning**: mike provider for multi-version docs
+3. **Theme**: Material with navigation features
+4. **Plugins**: search + mkdocstrings for API docs
+5. **Navigation**: Explicit nav structure
+
+## API Reference with mkdocstrings
+
+Create minimal markdown files that reference Python modules:
+
+```markdown
+# Panel API
+
+::: mypackage.panel.Panel
+
+::: mypackage.panel.PanelSync
+```
+
+mkdocstrings auto-generates documentation from docstrings. Configure in `mkdocs.yml`:
+- `docstring_style: google` - Use Google-style docstrings
+- `show_source: false` - Hide source code
+- `merge_init_into_class: true` - Combine `__init__` with class docs
+- `filters: ["!^_"]` - Exclude private members
+
+## Commands
+
+```bash
+# Serve locally with hot-reload
+mkdocs serve
+
+# Build static site
+mkdocs build
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy
+
+# Version management (mike)
+mike deploy --push --update-aliases 0.1.0 latest
+mike set-default --push latest
+```
+
+## Writing Guidelines
+
+1. **index.md**: Brief overview, key features as bullet list, installation snippet, "Where to Next" links
+2. **getting-started.md**: Prerequisites, step-by-step setup, minimal working example
+3. **API docs**: Let mkdocstrings generate from docstrings; add brief intro if needed
+4. **Guides**: Task-oriented, include code examples, link to related API docs
+
+## Templates
+
+- `templates/mkdocs.yml` - Configuration file
+- `templates/index.md` - Home page
+- `templates/getting-started.md` - Quickstart guide
+- `templates/api-reference.md` - API doc page using mkdocstrings

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/examples.md

@@ -0,0 +1,223 @@
+# MkDocs Generation Examples
+
+Real-world patterns from todoist-mcp and pydmp repositories.
+
+## Simple Documentation (todoist-mcp)
+
+Flat structure for smaller projects:
+
+```
+docs/
+├── index.md
+├── getting-started.md
+├── configuration.md
+└── tools.md
+```
+
+**mkdocs.yml nav:**
+```yaml
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - MCP Tools: tools.md
+```
+
+**index.md:**
+```markdown
+# Todoist MCP Server
+
+The Todoist MCP server is a Model Context Protocol (MCP) server for managing Todoist tasks from MCP clients like Claude Desktop.
+
+Use this documentation to:
+
+- Learn what the server can do
+- Set up Docker-based or local development environments
+- Configure environment variables and Redis caching
+- Explore the available MCP tools for task and project management
+```
+
+## Complex Documentation (pydmp)
+
+Nested structure for larger projects with API reference:
+
+```
+docs/
+├── index.md
+├── compatibility.md
+├── guide/
+│   ├── getting-started.md
+│   ├── cli.md
+│   ├── realtime-status.md
+│   ├── encryption.md
+│   └── migration.md
+└── api/
+    ├── panel.md
+    ├── protocol.md
+    ├── status.md
+    ├── entities/
+    │   ├── area.md
+    │   ├── zone.md
+    │   ├── output.md
+    │   ├── user.md
+    │   └── profile.md
+    └── protocol/
+        └── encryption.md
+```
+
+**mkdocs.yml nav:**
+```yaml
+nav:
+  - Home: index.md
+  - Panel Compatibility: compatibility.md
+  - Guide:
+      - Getting Started: guide/getting-started.md
+      - CLI: guide/cli.md
+      - Realtime Status (S3): guide/realtime-status.md
+      - Encryption & User Data: guide/encryption.md
+      - Migration: guide/migration.md
+  - API Reference:
+      - Panel: api/panel.md
+      - Entities:
+          - Area: api/entities/area.md
+          - Zone: api/entities/zone.md
+          - Output: api/entities/output.md
+          - User Code: api/entities/user.md
+          - User Profile: api/entities/profile.md
+      - Protocol:
+          - Protocol: api/protocol.md
+          - Encryption: api/protocol/encryption.md
+      - Realtime Server: api/status.md
+```
+
+## Index Page with Code Examples
+
+```markdown
+# PyDMP
+
+PyDMP is a platform-agnostic Python library for controlling DMP alarm panels.
+
+**Key Features:**
+
+- **Dual APIs**: Choose async for modern applications or sync for simple scripts
+- **High-level abstractions**: Work with panels, areas, zones, and outputs
+- **Built-in rate limiting**: Automatic command throttling
+
+## Installation
+
+\`\`\`bash
+pip install pydmp
+\`\`\`
+
+## Quick Start (Async)
+
+\`\`\`python
+import asyncio
+from pydmp import DMPPanel
+
+async def main():
+    panel = DMPPanel()
+    await panel.connect("192.168.1.100", "00001", "YOURKEY")
+    await panel.update_status()
+    areas = await panel.get_areas()
+    await panel.disconnect()
+
+asyncio.run(main())
+\`\`\`
+
+## Where to Next
+
+- [Getting Started](guide/getting-started.md) - Installation and connection
+- [CLI Guide](guide/cli.md) - Command-line interface
+- [API Reference](api/panel.md) - Complete API documentation
+```
+
+## API Reference Page (mkdocstrings)
+
+Minimal markdown that generates full API docs:
+
+```markdown
+# Panel API
+
+::: pydmp.panel.DMPPanel
+
+::: pydmp.panel_sync.DMPPanelSync
+```
+
+For entity docs:
+
+```markdown
+# Area
+
+::: pydmp.area.Area
+
+::: pydmp.area.AreaSync
+```
+
+## CLI Documentation Pattern
+
+```markdown
+# Command-Line Interface (CLI)
+
+PyDMP ships with a CLI for common operations.
+
+## Installation
+
+\`\`\`bash
+pip install pydmp[cli]
+\`\`\`
+
+## Configuration
+
+The CLI expects a YAML config file:
+
+\`\`\`yaml
+panel:
+  host: 192.168.1.100
+  account: "00001"
+  remote_key: "YOURKEY"
+\`\`\`
+
+## Commands
+
+### Areas & Zones
+\`\`\`bash
+pydmp get-areas [--json|-j]
+pydmp get-zones [--json|-j]
+\`\`\`
+
+### Arm/Disarm
+\`\`\`bash
+pydmp arm "1,2,3" [--bypass-faulted|-b] [--force-arm|-f]
+pydmp disarm <AREA> [--json|-j]
+\`\`\`
+
+## Examples
+
+\`\`\`bash
+# View areas with debug logs
+pydmp --debug get-areas
+
+# Arm area 1
+pydmp arm "1" --bypass-faulted
+\`\`\`
+```
+
+## pyproject.toml Integration
+
+```toml
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.4",
+    "mkdocstrings[python]>=0.24",
+    "mike>=2.0",
+]
+```
+
+Install and build:
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+mkdocs build
+```

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/templates/api-reference.md

@@ -0,0 +1,33 @@
+# API Reference
+
+<!--
+mkdocstrings generates API documentation from Python docstrings.
+Use the ::: directive to include a module, class, or function.
+
+Syntax:
+::: package.module.ClassName
+::: package.module.function_name
+
+The plugin reads docstrings and type hints to generate documentation.
+Use Google-style docstrings for best results.
+-->
+
+## [MainClass]
+
+::: [package].[module].[MainClass]
+
+## [SecondaryClass]
+
+::: [package].[module].[SecondaryClass]
+
+<!--
+For nested API structure, create subdirectories:
+
+docs/api/
+├── index.md      - API overview
+├── client.md     - ::: package.client.Client
+├── models.md     - ::: package.models
+└── entities/
+    ├── user.md   - ::: package.entities.User
+    └── item.md   - ::: package.entities.Item
+-->

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/templates/getting-started.md

@@ -0,0 +1,46 @@
+# Getting Started
+
+This guide walks through [what the guide covers].
+
+## Prerequisites
+
+- Python 3.9+
+- [Other prerequisites]
+
+## Installation
+
+```bash
+pip install [package-name]
+```
+
+## Configuration
+
+[Explain any required configuration, environment variables, or config files.]
+
+```bash
+# Example: copy and edit config
+cp config.example.yaml config.yaml
+```
+
+## Basic Usage
+
+### [First Concept/Task]
+
+```python
+from [package] import [Class]
+
+# Example code
+obj = [Class]()
+result = obj.method()
+```
+
+### [Second Concept/Task]
+
+```python
+# Example code for second task
+```
+
+## Next Steps
+
+- [Configuration](configuration.md) - Advanced configuration options
+- [API Reference](api.md) - Full API documentation

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/templates/index.md

@@ -0,0 +1,32 @@
+# [PROJECT_NAME]
+
+[One-sentence description of what this project does and who it's for.]
+
+**Key Features:**
+
+- **[Feature 1]**: [Brief description]
+- **[Feature 2]**: [Brief description]
+- **[Feature 3]**: [Brief description]
+
+## Installation
+
+```bash
+pip install [package-name]
+```
+
+## Quick Start
+
+```python
+from [package] import [MainClass]
+
+# Minimal working example
+client = [MainClass]()
+result = client.do_something()
+print(result)
+```
+
+## Where to Next
+
+- [Getting Started](getting-started.md) - Installation and setup walkthrough
+- [Configuration](configuration.md) - Configuration options
+- [API Reference](api.md) - Complete API documentation

ruff_sync-0.1.0.dev1/.agents/skills/mkdocs-generation/templates/mkdocs.yml

@@ -0,0 +1,59 @@
+# MkDocs Configuration Template
+# Replace placeholders: [SITE_NAME], [DESCRIPTION], [GITHUB_USER], [REPO_NAME], [PACKAGE_NAME]
+
+site_name: [SITE_NAME]
+site_description: [DESCRIPTION]
+site_url: https://[GITHUB_USER].github.io/[REPO_NAME]/
+repo_url: https://github.com/[GITHUB_USER]/[REPO_NAME]
+repo_name: [GITHUB_USER]/[REPO_NAME]
+
+extra:
+  version:
+    provider: mike
+    default: latest
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: false
+            members_order: source
+            show_if_no_docstring: true
+            show_signature_annotations: true
+            separate_signature: true
+            merge_init_into_class: true
+            show_root_heading: true
+            show_root_full_path: false
+            filters:
+              - "!^_"  # Exclude private members
+
+# Simple navigation (flat structure)
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - API Reference: api.md
+
+# Complex navigation example (nested structure)
+# nav:
+#   - Home: index.md
+#   - Guide:
+#       - Getting Started: guide/getting-started.md
+#       - CLI: guide/cli.md
+#       - Advanced: guide/advanced.md
+#   - API Reference:
+#       - Overview: api/index.md
+#       - Core:
+#           - Client: api/client.md
+#           - Models: api/models.md

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev1}/.github/workflows/ci.yaml

@@ -66,8 +66,10 @@ jobs:
 
   pre-publish:
     name: Test package installation
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: [static-analysis, tests]
+    if: >-
+      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'pull_request' && github.event.pull_request.draft == false)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -80,14 +82,29 @@ jobs:
         run: uv python install 3.10
 
       - name: Build package
-        run: uv build
+        run: |
+          echo "Building ruff-sync package..."
+          uv build
 
-      - name: Install and test packaged program
+      - name: Install packaged program
         run: |
+          echo "Installing built wheel..."
           uv tool install $(ls dist/*.whl)
-          ruff-sync --version
+          echo "Version: $(ruff-sync --version)"
+
+      - name: Test package installation (Pull)
+        run: |
+          echo "Testing ruff-sync pull against Kilo59/ruff-sync..."
           ruff-sync https://github.com/Kilo59/ruff-sync
+
+      - name: Test package installation (Check)
+        run: |
+          echo "Testing ruff-sync check against Kilo59/ruff-sync..."
           ruff-sync check https://github.com/Kilo59/ruff-sync
+
+      - name: Verify semantic check failure
+        run: |
+          echo "Verifying that --semantic check fails for kitchen-sink config (expected failure)..."
           ! ruff-sync check --semantic https://github.com/Kilo59/ruff-sync --path configs/kitchen-sink
 
   publish:

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev1}/.github/workflows/complexity.yaml

@@ -28,11 +28,10 @@ jobs:
           DIFF=$(wily diff ruff_sync.py tasks.py tests/ --no-detail -r origin/${{ github.event.pull_request.base.ref }})
           echo "$DIFF"
 
-          # Build multine output
-          DIFF="${DIFF//'%'/'%25'}"
-          DIFF="${DIFF//$'\n'/'%0A'}"
-          DIFF="${DIFF//$'\r'/'%0D'}"
-          echo "diff=$DIFF" >> "$GITHUB_OUTPUT"
+          # Build multiline output
+          echo "diff<<DIFF_EOF" >> "$GITHUB_OUTPUT"
+          echo "$DIFF" >> "$GITHUB_OUTPUT"
+          echo "DIFF_EOF" >> "$GITHUB_OUTPUT"
       - name: Add Wily PR Comment
         uses: marocchino/sticky-pull-request-comment@v2
         if: github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.number && steps.wily.outputs.diff != ''

ruff_sync-0.1.0.dev1/.github/workflows/docs.yaml

@@ -0,0 +1,32 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --group docs
+
+      - name: Build and deploy documentation
+        run: uv run mkdocs gh-deploy --force

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev1}/.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
       - id: check-json
       - id: check-yaml
         args: ["--unsafe"]
+        exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: no-commit-to-branch
@@ -21,6 +22,7 @@ repos:
     hooks:
       - id: prettier
         types_or: [yaml, json]
+        exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.11
     hooks:

{ruff_sync-0.0.5.dev2 → ruff_sync-0.1.0.dev1}/AGENTS.md

@@ -5,7 +5,7 @@
 **ruff-sync** is a CLI tool that synchronizes [Ruff](https://docs.astral.sh/ruff/) linter configuration across multiple Python projects. It downloads an upstream `pyproject.toml`, extracts the `[tool.ruff]` section, and merges it into a local project's `pyproject.toml` while preserving formatting, comments, and whitespace.
 
 - **GitHub Repository**: [`Kilo59/ruff-sync`](https://github.com/Kilo59/ruff-sync)
-- The entire application lives in a single module: `ruff_sync.py`.
+- The application uses a `src` layout in `src/ruff_sync/`.
 - Dev tasks are defined in `tasks.py` using [Invoke](https://www.pyinvoke.org/).
 
 ## GitHub Context
@@ -54,11 +54,14 @@ gh label list                           # See available labels
 
 ## Project Structure
 
-```
+```text
 .agents/               # Agent-specific instructions (Deep Standards)
   TESTING.md           # Mandatory testing patterns and rules
   workflows/           # Step-by-step guides for common tasks
-ruff_sync.py           # The entire application — CLI, merging logic, HTTP
+src/ruff_sync/         # The application source
+  __init__.py          # Public API
+  cli.py               # CLI, merging logic, HTTP
+  __main__.py          # -m support
 tasks.py               # Invoke tasks: lint, fmt, type-check, deps, new-case
 pyproject.toml         # Project config, dependencies, ruff/mypy settings
 tests/
@@ -114,7 +117,7 @@ uv run mypy .
 ```
 
 - mypy is configured in strict mode with `python_version = "3.10"`.
-- It checks `ruff_sync.py`, `tests/`, and `tasks.py`.
+- It checks `src/`, `tests/`, and `tasks.py`.
 - Tests have relaxed rules: `type-arg` and `no-untyped-def` are disabled for `tests.*`.
 - `tomlkit` returns complex union types — use `cast(Any, ...)` in tests when indexing parsed TOML documents to satisfy mypy without verbose type narrowing.
 
@@ -130,7 +133,7 @@ Or with coverage:
 uv run coverage run -m pytest -vv
 ```
 
-- Coverage is tracked for `ruff_sync.py` only.
+- Coverage is tracked for `src/ruff_sync/` only.
 - Tests use `respx` to mock HTTP calls and `pyfakefs` for filesystem mocking.
 - `pytest-asyncio` is in **strict** mode — async tests need the `@pytest.mark.asyncio` decorator.
 
@@ -165,13 +168,13 @@ uv run coverage run -m pytest -vv
 
 Defined in `tasks.py`. **ALWAYS** run these through uv: `uv run invoke <task>`
 
-| Task         | Alias        | Description                         |
-| ------------ | ------------ | ----------------------------------- |
-| `lint`       |              | Lint with ruff (auto-fixes by default) |
-| `fmt`        |              | Format with ruff format             |
-| `type-check` | `types`      | Type-check with mypy                |
-| `deps`       | `sync`       | Sync dependencies with uv           |
-| `new-case`   | `new-lifecycle-tomls` | Scaffold lifecycle TOML fixtures (See [Workflow](.agents/workflows/add-test-case.md)) |
+| Task         | Alias                 | Description                            |
+| ------------ | --------------------- | -------------------------------------- |
+| `lint`       |                       | Lint with ruff (auto-fixes by default) |
+| `fmt`        |                       | Format with ruff format                |
+| `type-check` | `types`               | Type-check with mypy                   |
+| `deps`       | `sync`                | Sync dependencies with uv              |
+| `new-case`   | `new-lifecycle-tomls` | Scaffold lifecycle TOML fixtures       |
 
 ## CI