affinity-sdk 0.4.7__tar.gz → 0.9.2__tar.gz

affinity_sdk-0.9.2/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "xaffinity",
+  "owner": {
+    "name": "Yaniv Golan"
+  },
+  "metadata": {
+    "description": "Plugins for Affinity CRM - Python SDK, CLI, and MCP integrations"
+  },
+  "plugins": [
+    {
+      "name": "sdk",
+      "source": "./plugins/affinity-sdk/.claude-plugin",
+      "description": "Python SDK for Affinity CRM - typed IDs, async support, pagination patterns for developers"
+    },
+    {
+      "name": "cli",
+      "source": "./plugins/xaffinity-cli/.claude-plugin",
+      "description": "Command-line interface for Affinity CRM - search, export, filter CRM data via xaffinity commands"
+    },
+    {
+      "name": "mcp",
+      "source": "./mcp/.claude-plugin",
+      "description": "MCP server for Affinity CRM - workflow tools, relationship intelligence, pipeline management"
+    }
+  ]
+}

affinity_sdk-0.9.2/.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,31 @@
+---
+name: Release
+about: Checklist for SDK or MCP releases
+---
+
+## Release Type
+
+- [ ] SDK Release (vX.Y.Z)
+- [ ] MCP Release (plugin-vX.Y.Z)
+
+## SDK Release Checklist (vX.Y.Z)
+
+- [ ] Version bumped in `pyproject.toml`
+- [ ] Plugin versions synced (pre-commit should handle)
+- [ ] `CHANGELOG.md` updated with breaking changes noted
+- [ ] If CLI output format changed: MCP `COMPATIBILITY` updated
+- [ ] Tests pass locally and in CI
+
+## MCP Release Checklist (plugin-vX.Y.Z)
+
+- [ ] Version bumped in `mcp/VERSION`
+- [ ] `mcp/.claude-plugin/plugin.json` version updated
+- [ ] `mcp/mcpb.conf` MCPB_VERSION updated
+- [ ] `mcp/COMPATIBILITY` CLI requirements updated if needed
+- [ ] `mcp/CHANGELOG.md` documents CLI compatibility
+- [ ] Builds successfully: `cd mcp && make all verify`
+
+## Post-Merge
+
+- [ ] Tag pushed: `git tag vX.Y.Z && git push --tags` (SDK)
+- [ ] Tag pushed: `git tag plugin-vX.Y.Z && git push --tags` (MCP)

affinity_sdk-0.9.2/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  mcp-plugin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build MCP plugin
+        run: make -C mcp plugin
+
+      - name: Verify plugin structure
+        run: |
+          # Ensure critical files exist after build (ZIP-based distribution)
+          make -C mcp verify
+          test -f mcp/.claude-plugin/xaffinity-mcp.sh
+          test -f mcp/.claude-plugin/plugin.json
+          test -f mcp/.claude-plugin/xaffinity-mcp-plugin.zip
+          test -f mcp/.claude-plugin/VERSION
+          echo "Plugin structure validated successfully"
+
+      - name: Test ZIP extraction
+        run: |
+          cd mcp/.claude-plugin
+          mkdir -p .mcp-extracted
+          unzip -q xaffinity-mcp-plugin.zip -d .mcp-extracted
+          test -x .mcp-extracted/xaffinity-mcp.sh
+          test -d .mcp-extracted/tools
+          test -d .mcp-extracted/prompts
+          echo "ZIP extraction test passed"
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff format --check .
+          ruff check .
+
+      - name: Type check
+        run: |
+          mypy affinity
+
+      - name: Test
+        run: |
+          pytest --cov=affinity --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+      - name: Traceability mapping is up to date
+        run: |
+          if [ -d docs/internal ]; then
+            python tools/generate_requirements_mapping.py
+            git diff --exit-code docs/internal/requirements_to_tests_mapping.md
+          else
+            echo "Skipping traceability mapping (docs/internal not present in repo checkout)."
+          fi
+
+      - name: CLI commands registry is valid
+        run: |
+          # Verify registry file exists and is valid JSON with expected structure
+          python -c "
+          import json
+          import sys
+          with open('mcp/.registry/commands.json') as f:
+              data = json.load(f)
+          assert 'commands' in data, 'Missing commands key'
+          assert isinstance(data['commands'], list), 'commands must be a list'
+          assert len(data['commands']) > 0, 'commands list is empty'
+          for cmd in data['commands']:
+              assert 'name' in cmd, f'Command missing name: {cmd}'
+              assert 'category' in cmd, f'Command {cmd[\"name\"]} missing category'
+              assert cmd['category'] in ('read', 'write', 'local'), f'Invalid category for {cmd[\"name\"]}'
+          print(f'Registry valid: {len(data[\"commands\"])} commands')
+          "
+          # Regenerate registry and verify it matches committed version
+          python tools/generate_cli_commands_registry.py
+          git diff --exit-code mcp/.registry/commands.json
+
+  test-timezone:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tz: ["UTC", "America/New_York", "Europe/London", "Asia/Tokyo"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Test with TZ=${{ matrix.tz }}
+        env:
+          TZ: ${{ matrix.tz }}
+        run: |
+          pytest tests/test_isodatetime.py -v

{affinity_sdk-0.4.7 → affinity_sdk-0.9.2}/.github/workflows/docs.yml

@@ -13,12 +13,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -54,14 +54,14 @@ jobs:
       contents: write
     concurrency:
       group: docs-deploy
-      cancel-in-progress: true
+      cancel-in-progress: false
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -81,6 +81,10 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
+      - name: Fetch gh-pages branch
+        run: |
+          git fetch origin gh-pages:gh-pages || true
+
       - name: Deploy (dev)
         if: github.ref == 'refs/heads/main'
         run: |

{affinity_sdk-0.4.7 → affinity_sdk-0.9.2}/.github/workflows/labels.yml

@@ -15,7 +15,7 @@ jobs:
   sync:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Sync labels
         uses: EndBug/label-sync@v2
         with:

{affinity_sdk-0.4.7 → affinity_sdk-0.9.2}/.github/workflows/linkcheck.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip

{affinity_sdk-0.4.7 → affinity_sdk-0.9.2}/.github/workflows/openapi-validation.yml

@@ -11,10 +11,10 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip

affinity_sdk-0.9.2/.github/workflows/plugin-build.yml

@@ -0,0 +1,106 @@
+name: Build MCP Plugin
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'mcp/**'
+      - '!mcp/dist/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install jq
+        run: sudo apt-get install -y jq
+
+      - name: Install mcp-bash framework
+        run: |
+          # Source version and commit from lockfile (single source of truth)
+          source mcp/mcp-bash.lock
+          echo "Installing mcp-bash v${MCPBASH_VERSION} (${MCPBASH_COMMIT})"
+          curl -fsSL https://raw.githubusercontent.com/yaniv-golan/mcp-bash-framework/main/install.sh | \
+            bash -s -- --version "v${MCPBASH_VERSION}" --yes
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          # Verify installed commit matches lockfile
+          INSTALLED_COMMIT=$(git -C "${XDG_DATA_HOME:-$HOME/.local/share}/mcp-bash" rev-parse HEAD)
+          if [[ "$INSTALLED_COMMIT" != "$MCPBASH_COMMIT" ]]; then
+            echo "::error::mcp-bash commit mismatch: expected $MCPBASH_COMMIT, got $INSTALLED_COMMIT"
+            exit 1
+          fi
+
+      - name: Verify mcp-bash installation
+        run: |
+          mcp-bash --version
+          echo "mcp-bash installed successfully"
+
+      - name: Build MCP plugin ZIP
+        run: make -C mcp plugin
+
+      - name: Verify plugin structure
+        run: |
+          make -C mcp verify
+          test -f mcp/.claude-plugin/xaffinity-mcp.sh
+          test -f mcp/.claude-plugin/plugin.json
+          test -f mcp/.claude-plugin/xaffinity-mcp-plugin.zip
+          test -f mcp/.claude-plugin/VERSION
+          echo "Plugin structure validated"
+
+      - name: Test extraction
+        run: |
+          cd mcp/.claude-plugin
+          mkdir -p .mcp-extracted
+          unzip -q xaffinity-mcp-plugin.zip -d .mcp-extracted
+          test -x .mcp-extracted/xaffinity-mcp.sh
+          test -f .mcp-extracted/VERSION
+          rm -rf .mcp-extracted
+          echo "Extraction test passed"
+
+      - name: Validate MCPB configuration
+        run: |
+          cd mcp
+          mcp-bash bundle --validate
+          echo "MCPB configuration validated"
+
+      - name: Build MCPB bundle
+        run: |
+          cd mcp
+          mcp-bash bundle --output dist --verbose
+          ls -la dist/*.mcpb
+          echo "MCPB bundle created"
+
+      - name: Validate MCPB bundle structure
+        run: |
+          cd mcp
+          MCPB_FILE=$(ls dist/*.mcpb | head -1)
+          unzip -t "$MCPB_FILE"
+          unzip -p "$MCPB_FILE" manifest.json | jq .
+          echo "MCPB bundle structure validated"
+
+      - name: Test MCPB bundle health check
+        run: |
+          cd mcp
+          MCPB_FILE=$(ls dist/*.mcpb | head -1)
+          EXTRACT_DIR=$(mktemp -d)
+          unzip -q "$MCPB_FILE" -d "$EXTRACT_DIR"
+          # Test the wrapper script health check
+          "$EXTRACT_DIR/server/run-server.sh" --health || echo "Health check not available (expected if CLI not configured)"
+          rm -rf "$EXTRACT_DIR"
+          echo "MCPB bundle test completed"
+
+      - name: Upload plugin artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: mcp-plugin
+          path: |
+            mcp/.claude-plugin/xaffinity-mcp-plugin.zip
+            mcp/dist/*.mcpb
+          retention-days: 30

affinity_sdk-0.9.2/.github/workflows/plugin-release.yml

@@ -0,0 +1,152 @@
+name: Release MCP Plugin
+
+on:
+  push:
+    tags: ["mcp-v*.*.*"]  # Renamed from plugin-v*
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to release (without prefix)"
+        required: true
+        type: string
+      triggered_by:
+        description: "What triggered this release"
+        required: false
+        type: string
+        default: "tag"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g., mcp-v1.0.0)'
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Determine version and tag
+        id: version
+        run: |
+          set -euo pipefail
+          if [[ -n "${{ inputs.version }}" ]]; then
+            # Called via workflow_call
+            echo "version=${{ inputs.version }}" >> $GITHUB_OUTPUT
+            echo "tag_name=mcp-v${{ inputs.version }}" >> $GITHUB_OUTPUT
+            echo "is_workflow_call=true" >> $GITHUB_OUTPUT
+            echo "Mode: workflow_call, version=${{ inputs.version }}"
+          else
+            # Called via tag push or workflow_dispatch
+            TAG_NAME="${{ github.event.inputs.tag || github.ref_name }}"
+            VERSION="${TAG_NAME#mcp-v}"
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "tag_name=$TAG_NAME" >> $GITHUB_OUTPUT
+            echo "is_workflow_call=false" >> $GITHUB_OUTPUT
+            echo "Mode: tag/dispatch, tag=$TAG_NAME, version=$VERSION"
+          fi
+
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ steps.version.outputs.is_workflow_call == 'true' && 'main' || (github.event.inputs.tag || github.ref) }}
+
+      - name: Validate version matches VERSION file
+        run: |
+          set -euo pipefail
+          FILE_VERSION=$(cat mcp/VERSION | tr -d '[:space:]')
+          INPUT_VERSION="${{ steps.version.outputs.version }}"
+          if [[ "$FILE_VERSION" != "$INPUT_VERSION" ]]; then
+            echo "::error::Version mismatch: mcp/VERSION=$FILE_VERSION, expected=$INPUT_VERSION"
+            exit 1
+          fi
+          echo "Version validated: $FILE_VERSION"
+
+      - name: Install jq
+        run: sudo apt-get install -y jq
+
+      - name: Install mcp-bash framework
+        run: |
+          # Source version and commit from lockfile (single source of truth)
+          source mcp/mcp-bash.lock
+          echo "Installing mcp-bash v${MCPBASH_VERSION} (${MCPBASH_COMMIT})"
+          curl -fsSL https://raw.githubusercontent.com/yaniv-golan/mcp-bash-framework/main/install.sh | \
+            bash -s -- --version "v${MCPBASH_VERSION}" --yes
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          # Verify installed commit matches lockfile
+          INSTALLED_COMMIT=$(git -C "${XDG_DATA_HOME:-$HOME/.local/share}/mcp-bash" rev-parse HEAD)
+          if [[ "$INSTALLED_COMMIT" != "$MCPBASH_COMMIT" ]]; then
+            echo "::error::mcp-bash commit mismatch: expected $MCPBASH_COMMIT, got $INSTALLED_COMMIT"
+            exit 1
+          fi
+
+      - name: Verify mcp-bash installation
+        run: mcp-bash --version
+
+      - name: Build Claude Code plugin ZIP
+        run: |
+          cd mcp
+          make plugin
+          echo "Plugin version: $(cat .claude-plugin/VERSION)"
+          ls -la .claude-plugin/xaffinity-mcp-plugin.zip
+
+      - name: Validate MCPB configuration
+        run: |
+          cd mcp
+          mcp-bash bundle --validate
+
+      - name: Build MCPB bundle
+        run: |
+          cd mcp
+          mcp-bash bundle --output dist --verbose
+          ls -la dist/*.mcpb
+
+      - name: Validate MCPB bundle structure
+        run: |
+          cd mcp
+          MCPB_FILE=$(ls dist/*.mcpb | head -1)
+          unzip -t "$MCPB_FILE"
+          unzip -p "$MCPB_FILE" manifest.json | jq .
+          echo "MCPB bundle validated"
+
+      - name: Test MCPB bundle health check
+        run: |
+          cd mcp
+          MCPB_FILE=$(ls dist/*.mcpb | head -1)
+          EXTRACT_DIR=$(mktemp -d)
+          unzip -q "$MCPB_FILE" -d "$EXTRACT_DIR"
+          "$EXTRACT_DIR/server/run-server.sh" --health || echo "Health check not available (expected if CLI not configured)"
+          rm -rf "$EXTRACT_DIR"
+
+      - name: Create and push tag
+        if: steps.version.outputs.is_workflow_call == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.tag_name }}" -m "Release ${{ steps.version.outputs.tag_name }}"
+          git push origin "${{ steps.version.outputs.tag_name }}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag_name }}
+          files: |
+            mcp/.claude-plugin/xaffinity-mcp-plugin.zip
+            mcp/dist/*.mcpb
+          generate_release_notes: true
+          name: MCP Server ${{ steps.version.outputs.tag_name }}
+          body: |
+            ## Installation
+
+            ### One-click install (Claude Desktop)
+            Download `xaffinity-mcp-*.mcpb` and double-click or drag to Claude Desktop.
+
+            ### Claude Code
+            ```bash
+            /plugin marketplace add yaniv-golan/affinity-sdk
+            /plugin install mcp@xaffinity
+            ```
+
+            ### Manual configuration
+            Download `xaffinity-mcp-plugin.zip` and configure your MCP client manually.
+            See [documentation](https://yaniv-golan.github.io/affinity-sdk/latest/mcp/) for details.

affinity_sdk-0.9.2/.github/workflows/release-detect.yml

@@ -0,0 +1,98 @@
+name: Release Detection
+
+# Triggers releases automatically when version files change on main
+# Only runs AFTER CI passes successfully
+#
+# Detection strategy: Compare current version against existing release tags.
+# This is more robust than checking HEAD~1 because it works regardless of
+# how many commits are pushed together, squash merges, rebases, etc.
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  detect-changes:
+    # Only run if CI passed and it was a push (not PR)
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      sdk_changed: ${{ steps.changes.outputs.sdk }}
+      mcp_changed: ${{ steps.changes.outputs.mcp }}
+      sdk_version: ${{ steps.versions.outputs.sdk }}
+      mcp_version: ${{ steps.versions.outputs.mcp }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0  # Full history needed to check tags
+
+      - name: Extract versions
+        id: versions
+        run: |
+          set -euo pipefail
+          SDK_VERSION=$(grep '^version = ' pyproject.toml | head -1 | cut -d'"' -f2)
+          MCP_VERSION=$(cat mcp/VERSION | tr -d '[:space:]')
+          echo "sdk=$SDK_VERSION" >> $GITHUB_OUTPUT
+          echo "mcp=$MCP_VERSION" >> $GITHUB_OUTPUT
+          echo "SDK version in pyproject.toml: $SDK_VERSION"
+          echo "MCP version in mcp/VERSION: $MCP_VERSION"
+
+      - name: Detect unreleased versions
+        id: changes
+        run: |
+          set -euo pipefail
+
+          SDK_VERSION="${{ steps.versions.outputs.sdk }}"
+          MCP_VERSION="${{ steps.versions.outputs.mcp }}"
+
+          echo "Checking if releases exist for current versions..."
+
+          # Check if SDK version has a release tag
+          SDK_TAG="v${SDK_VERSION}"
+          if git tag -l "$SDK_TAG" | grep -q "^${SDK_TAG}$"; then
+            echo "SDK tag $SDK_TAG already exists - no release needed"
+          else
+            echo "SDK tag $SDK_TAG does not exist - release needed"
+            echo "sdk=true" >> $GITHUB_OUTPUT
+          fi
+
+          # Check if MCP version has a release tag
+          MCP_TAG="mcp-v${MCP_VERSION}"
+          if git tag -l "$MCP_TAG" | grep -q "^${MCP_TAG}$"; then
+            echo "MCP tag $MCP_TAG already exists - no release needed"
+          else
+            echo "MCP tag $MCP_TAG does not exist - release needed"
+            echo "mcp=true" >> $GITHUB_OUTPUT
+          fi
+
+  trigger-sdk-release:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.sdk_changed == 'true'
+    uses: ./.github/workflows/release.yml
+    with:
+      version: ${{ needs.detect-changes.outputs.sdk_version }}
+      triggered_by: version-bump
+    secrets: inherit
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+
+  trigger-mcp-release:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.mcp_changed == 'true'
+    uses: ./.github/workflows/plugin-release.yml
+    with:
+      version: ${{ needs.detect-changes.outputs.mcp_version }}
+      triggered_by: version-bump
+    secrets: inherit
+    permissions:
+      contents: write