hull-core 0.1.0b1__tar.gz

hull_core-0.1.0b1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default code owner — required reviewer for all PRs
+*       @n24q02m

hull_core-0.1.0b1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+
+- OS: [e.g. macOS, Linux, Windows]
+- Go version: [output of `go version`]
+- hull-core version: [output of `hull-core --version`]
+- Installation method: [e.g. go install, Docker, brew, scoop, apt, direct binary]
+
+**Additional context**
+Add any other context about the problem here.

hull_core-0.1.0b1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

hull_core-0.1.0b1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Description
+<!-- Describe what this PR does and why -->
+
+## Changes
+<!-- List the key changes -->
+-
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+
+## Testing
+- [ ] Existing tests pass
+- [ ] Added new tests for the changes
+- [ ] Tested manually
+
+## Screenshots
+<!-- If applicable, add screenshots to help explain your changes -->
+
+## Checklist
+- [ ] My code follows the project's coding standards
+- [ ] I have commented my code where necessary
+- [ ] I have updated documentation if needed
+- [ ] My changes generate no new warnings

hull_core-0.1.0b1/.github/repo-settings.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "tier": 2,
+  "description": "hull is the shared monorepo core for the wet, crg and mnemo self-hosted stack",
+  "homepage": "",
+  "topics": [
+    "mcp",
+    "model-context-protocol",
+    "python",
+    "self-hosted"
+  ]
+}

hull_core-0.1.0b1/.github/rulesets/main.json

@@ -0,0 +1,64 @@
+{
+  "name": "Main Branch Rules",
+  "target": "branch",
+  "source_type": "Repository",
+  "source": "n24q02m/hull",
+  "enforcement": "active",
+  "bypass_actors": [
+    {
+      "actor_id": 5,
+      "actor_type": "RepositoryRole",
+      "bypass_mode": "always"
+    },
+    {
+      "actor_id": 3200052,
+      "actor_type": "Integration",
+      "bypass_mode": "always"
+    }
+  ],
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": [
+        "~DEFAULT_BRANCH"
+      ]
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_linear_history"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "require_extra_approval_for_unattributed_changes": true,
+        "allowed_merge_methods": [
+          "squash"
+        ]
+      }
+    },
+    {
+      "type": "code_scanning",
+      "parameters": {
+        "code_scanning_tools": [
+          {
+            "tool": "CodeQL",
+            "security_alerts_threshold": "high_or_higher",
+            "alerts_threshold": "errors"
+          }
+        ]
+      }
+    }
+  ]
+}

hull_core-0.1.0b1/.github/workflows/cd.yml

@@ -0,0 +1,388 @@
+# =============================================================================
+# CD Template: Python. Publish steps are opt-in per repo via
+# vars.PUBLISH_PYPI / vars.PUBLISH_DOCKER / vars.PUBLISH_MCP_REGISTRY.
+# Managed by n24q02m repo-bootstrap; local changes may be overwritten.
+#
+# Pipeline: PSR v10 -> PyPI -> Docker multi-arch (amd64+arm64) -> MCP Registry
+# CUSTOMIZE: Search for "# CUSTOMIZE:" comments and adjust for your repo.
+# =============================================================================
+name: CD
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: "Release type"
+        required: true
+        type: choice
+        options:
+          - beta
+          - stable
+      publish_existing_tag:
+        description: "Recovery only: publish an already-created tag (e.g. v3.1.0), skipping semantic-release. Use when the auto-computed version's tag name is permanently reserved by a GitHub immutable release."
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+env:
+  # Release lane: dispatch-only (release_type=beta, then stable); a push never releases.
+  RELEASE_TYPE: ${{ inputs.release_type }}
+  DOCKERHUB_IMAGE: ${{ secrets.DOCKERHUB_USERNAME }}/hull-core
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  # ============================================================================
+  # README registry metadata: the package carries the repo's README to PyPI, so
+  # a manifest that names a file which is not there publishes an empty project
+  # page. Runs before the release rather than beside it -- a PyPI upload cannot
+  # be undone, only yanked.
+  # ============================================================================
+  readme-sync:
+    name: Verify README registry metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.13"
+      - name: Verify README registry metadata
+        run: python scripts/repo-bootstrap/verify_readme_sync.py --repo-root=.
+
+  # ============================================================================
+  # Release: PSR v10
+  # ============================================================================
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    outputs:
+      released: ${{ steps.release.outputs.released || steps.forced.outputs.released }}
+      tag: ${{ steps.release.outputs.tag || steps.forced.outputs.tag }}
+      version: ${{ steps.release.outputs.version || steps.forced.outputs.version }}
+      is_prerelease: ${{ steps.release.outputs.is_prerelease || steps.forced.outputs.is_prerelease }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Generate GitHub App Token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.CI_APP_ID }}
+          private-key: ${{ secrets.CI_APP_KEY }}
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 0
+
+      # Version bump runs on the fork (orphan-tag + registry-collision guards).
+      # The publish step below stays upstream — the fork does not replace it.
+      - uses: n24q02m/better-semantic-release@087b84e8d2ba75bdec350924d3bf8247088e0b1a # v1.4.0
+        id: release
+        if: inputs.publish_existing_tag == ''
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+          prerelease: ${{ env.RELEASE_TYPE == 'beta' }}
+          prerelease_token: beta
+
+      - uses: python-semantic-release/publish-action@5a5718ce47b892ef699f2972dae122297771d641 # v10.6.1
+        if: inputs.publish_existing_tag == '' && steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+          tag: ${{ steps.release.outputs.tag }}
+
+      - name: Use existing tag (immutable-release recovery)
+        id: forced
+        if: inputs.publish_existing_tag != ''
+        run: |
+          TAG="${{ inputs.publish_existing_tag }}"
+          VERSION="${TAG#v}"
+          {
+            echo "released=true"
+            echo "tag=$TAG"
+            echo "version=$VERSION"
+            echo "is_prerelease=false"
+          } >> "$GITHUB_OUTPUT"
+
+  # ============================================================================
+  # Notify Downstream
+  # ============================================================================
+  # A core/shared repo cutting a stable release has to open a tracking issue in
+  # every repo that pins it, or downstream pins drift silently. The dispatch goes
+  # to one hub repo that fans the issues out; `n24q02m/n24q02m` is that hub as a
+  # literal, copied from the repo this template was measured against rather than
+  # derived from `n24q02m` -- the hub happening to share the owner's name is not
+  # a rule this template gets to assume.
+  #
+  # Stable only: `is_prerelease != 'true'`. A beta cutting downstream issues would
+  # file the same issue again at stable.
+  #
+  # New repositories and repositories already using the gate require
+  # NOTIFY_DOWNSTREAM, because this template also lands on non-core Python repos.
+  # During retrofit, an existing ungated notify-downstream job stays ungated:
+  # silently adding an unset-variable gate would stop a live release behavior.
+  # apply.py detects only that existing job block; it does not infer core status
+  # from a repository name.
+  notify-downstream:
+    name: Notify Downstream
+    needs: [release]
+    if: >-
+      needs.release.outputs.released == 'true'
+      && needs.release.outputs.is_prerelease != 'true'
+      && vars.NOTIFY_DOWNSTREAM == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Generate GitHub App Token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.CI_APP_ID }}
+          private-key: ${{ secrets.CI_APP_KEY }}
+          # Without owner/repositories the token is scoped to THIS repo only
+          # and the dispatch 403s ("Resource not accessible by integration").
+          # Scope to the target repo, nothing more.
+          owner: n24q02m
+          repositories: n24q02m
+
+      - name: Dispatch core-update
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          gh api repos/n24q02m/n24q02m/dispatches \
+            -f event_type=core-update \
+            -f 'client_payload[core]=hull-core' \
+            -f 'client_payload[version]=${{ needs.release.outputs.version }}' \
+            -f 'client_payload[tag]=${{ needs.release.outputs.tag }}' \
+            -f 'client_payload[release_url]=https://github.com/${{ github.repository }}/releases/tag/${{ needs.release.outputs.tag }}'
+
+  # ============================================================================
+  # Publish to PyPI
+  # ============================================================================
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [readme-sync, release]
+    if: needs.release.outputs.released == 'true' && vars.PUBLISH_PYPI == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  # ============================================================================
+  # Build Docker (multi-arch: amd64 + arm64)
+  # ============================================================================
+  build-docker:
+    name: Build Docker (${{ matrix.platform }})
+    # readme-sync, because this job pushes an image to a registry and
+    # merge-docker then publishes ./README.md as the Docker Hub description.
+    # The gate is only a gate if it runs BEFORE the push.
+    needs: [readme-sync, release]
+    if: needs.release.outputs.released == 'true' && vars.PUBLISH_DOCKER == 'true'
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+            artifact: linux-amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            artifact: linux-arm64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        id: build
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,"name=${{ env.DOCKERHUB_IMAGE }},${{ env.GHCR_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ github.ref_name }}-${{ matrix.artifact }}
+          cache-to: type=gha,mode=max,scope=${{ github.ref_name }}-${{ matrix.artifact }}
+      - run: |
+          mkdir -p ${{ runner.temp }}/digests
+          echo "${{ steps.build.outputs.digest }}" > "${{ runner.temp }}/digests/${{ matrix.artifact }}"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: digest-${{ matrix.artifact }}
+          path: ${{ runner.temp }}/digests/*
+          retention-days: 1
+
+  # ============================================================================
+  # Merge Docker Manifests
+  # ============================================================================
+  merge-docker:
+    name: Merge Docker Manifests
+    needs: [release, build-docker]
+    if: needs.release.outputs.released == 'true' && vars.PUBLISH_DOCKER == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          pattern: digest-*
+          path: ${{ runner.temp }}/digests
+          merge-multiple: true
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create and push manifests
+        env:
+          VERSION: ${{ needs.release.outputs.version }}
+          IS_PRERELEASE: ${{ needs.release.outputs.is_prerelease }}
+        run: |
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            TAGS="beta ${VERSION}"
+          else
+            MAJOR=$(echo "$VERSION" | cut -d. -f1)
+            MINOR=$(echo "$VERSION" | cut -d. -f1-2)
+            TAGS="latest ${VERSION} ${MINOR} ${MAJOR}"
+          fi
+
+          for IMAGE in "$DOCKERHUB_IMAGE" "$GHCR_IMAGE"; do
+            tag_args=()
+            for TAG in $TAGS; do
+              tag_args+=("-t" "${IMAGE}:${TAG}")
+            done
+
+            digest_args=()
+            for digest_file in "${{ runner.temp }}/digests/"*; do
+              while IFS= read -r digest; do
+                if [ -n "$digest" ]; then
+                  digest_args+=("${IMAGE}@${digest}")
+                fi
+              done < "$digest_file"
+            done
+
+            docker buildx imagetools create "${tag_args[@]}" "${digest_args[@]}"
+          done
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          sparse-checkout: README.md
+      - uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5.0.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          # CUSTOMIZE: DockerHub repository name
+          repository: ${{ env.DOCKERHUB_IMAGE }}
+          short-description: ${{ github.event.repository.description }}
+          readme-filepath: ./README.md
+
+  # ============================================================================
+  # Publish to MCP Registry (stable only)
+  # ============================================================================
+  publish-mcp-registry:
+    name: Publish to MCP Registry
+    needs: [release, publish-pypi, merge-docker]
+    if: >-
+      needs.release.outputs.released == 'true'
+      && needs.release.outputs.is_prerelease != 'true'
+      && vars.PUBLISH_PYPI == 'true'
+      && vars.PUBLISH_DOCKER == 'true'
+      && vars.PUBLISH_MCP_REGISTRY == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Update server.json version
+        run: |
+          VERSION="${{ needs.release.outputs.version }}"
+          jq --arg v "$VERSION" '
+            .version = $v |
+            .packages = [.packages[] |
+              if .registryType == "oci" then del(.version)
+              else .version = $v
+              end
+            ]
+          ' server.json > server.json.tmp && mv server.json.tmp server.json
+
+      - name: Install MCP Publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Login to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: |
+          set +e
+          out=$(./mcp-publisher publish 2>&1)
+          rc=$?
+          echo "$out"
+          set -e
+          if [ $rc -ne 0 ] && echo "$out" | grep -q "cannot publish duplicate version"; then
+            echo "duplicate version already in registry - idempotent recovery, treating as success"
+            exit 0
+          fi
+          exit $rc