Release: merge release into main

.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "permissions": {}
+}

.github/workflows/android-native.yml

@@ -0,0 +1,40 @@
+name: Android Native CI
+
+on:
+  push:
+    branches: [ "develop", "main" ]
+  pull_request:
+    branches: [ "develop", "main" ]
+
+concurrency:
+  # A newer push to the same ref supersedes this run; frees the shared macOS runners.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  compile:
+    name: Compile Android Native
+    # ubuntu-latest is sufficient and faster for cross-compiling to Android Native
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          cache: 'gradle'
+
+      - name: Cache Konan
+        uses: actions/cache@v4
+        with:
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
+
+      - name: Compile Android Native Arm64
+        # Compile Android Native which includes commonMain + nativeMain + artMain
+        run: ./gradlew :python-multiplatform:compileKotlinAndroidNativeArm64 --console=plain

.github/workflows/desktop.yml

@@ -0,0 +1,46 @@
+name: Desktop CI
+
+on:
+  push:
+    branches: [ "develop", "main" ]
+  pull_request:
+    branches: [ "develop", "main" ]
+
+concurrency:
+  # A newer push to the same ref supersedes this run; frees the shared macOS runners.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Desktop Tests
+    # macOS runner is used to compile for iOS and is also good for Desktop.
+    # We use ubuntu, macos, and windows to cover the major desktop platforms.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          # This automatically caches ~/.gradle/caches and ~/.gradle/wrapper
+          cache: 'gradle'
+
+      - name: Cache Konan
+        uses: actions/cache@v4
+        with:
+          # Cache Kotlin Native compiler and dependencies
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
+
+      - name: Run Desktop Tests
+        # Using --console=plain so logs are readable in GitHub Actions
+        run: ./gradlew :python-multiplatform:desktopTest --console=plain

.github/workflows/ios.yml

@@ -0,0 +1,40 @@
+name: iOS CI
+
+on:
+  push:
+    branches: [ "develop", "main" ]
+  pull_request:
+    branches: [ "develop", "main" ]
+
+concurrency:
+  # A newer push to the same ref supersedes this run; frees the shared macOS runners.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  compile:
+    name: Compile iOS Simulator Arm64
+    # macos-latest is required since iOS compilation needs Xcode
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          cache: 'gradle'
+
+      - name: Cache Konan
+        uses: actions/cache@v4
+        with:
+          path: ~/.konan
+          key: ${{ runner.os }}-konan-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-konan-
+
+      - name: Compile iOS Simulator Arm64
+        # Compile iOS Simulator which includes commonMain + nativeMain + iosMain
+        run: ./gradlew :python-multiplatform:compileKotlinIosSimulatorArm64 --console=plain

.github/workflows/pages.yml

@@ -0,0 +1,30 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/guide
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release-sync.yml

@@ -0,0 +1,52 @@
+name: Release sync
+
+# `release` is generated here, not maintained: every push to develop rebuilds it
+# as one commit on top of that develop commit (develop minus the Markdown files
+# that must not reach main), force-pushes it, and keeps one release -> main PR open.
+on:
+  push:
+    branches: [develop]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Sync release branch
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          # Not used as a base (release is regenerated); the script reads the
+          # remote sha itself for --force-with-lease.
+          bash tools/release/sync-release.sh --source "${GITHUB_SHA}" --push
+
+      - name: Open or update PR release -> main
+        env:
+          # Needs "Allow GitHub Actions to create and approve pull requests" in the
+          # repository's Actions settings. RELEASE_PR_TOKEN is optional.
+          GH_TOKEN: ${{ secrets.RELEASE_PR_TOKEN || github.token }}
+        run: |
+          set -eu
+          if ! git rev-parse -q --verify refs/heads/release >/dev/null; then exit 0; fi
+          if [ "$(git rev-parse release^{tree})" = "$(git rev-parse origin/main^{tree} 2>/dev/null || true)" ]; then
+            echo "release already equals main; nothing to PR"; exit 0
+          fi
+          title="Release: merge release into main"
+          body="Automated sync of \`develop\` (${GITHUB_SHA::7}) into \`release\`. Markdown outside README.md and docs/ subfolders is removed by tools/release/sync-release.sh."
+          existing="$(gh pr list --head release --base main --state open --json number --jq '.[0].number // empty')"
+          if [ -n "$existing" ]; then
+            gh pr edit "$existing" --title "$title" --body "$body"
+          else
+            gh pr create --head release --base main --title "$title" --body "$body"
+          fi

.github/workflows/stubs.yml

@@ -0,0 +1,149 @@
+name: Kotlin-name stubs
+
+# Issue #32: pythonx-compose consumes the binder's Kotlin-name `.pyi` stubs for the real Compose jars
+# but cannot run this repository's Gradle build. This job runs the stub task over the Compose version the
+# build resolves (`compose-plugin` in gradle/libs.versions.toml) and publishes the result.
+#
+#   - every push to develop and every pull request: the stubs are generated, type-checked against
+#     tools/stubs/consumer.py with mypy (issue #31), and uploaded as the workflow artifact `kotlin-stubs`;
+#   - every `v*` tag: the same stubs are also attached to the tag's GitHub release as `kotlin-stubs.zip`.
+
+on:
+  push:
+    branches: [ "develop" ]
+    tags: [ "v*" ]
+  pull_request:
+    branches: [ "develop" ]
+    paths:
+      - "python-multiplatform-gradle-plugin/**"
+      - "ksp-fixtures/compose/**"
+      - "tools/stubs/**"
+      - "gradle/libs.versions.toml"
+      - ".github/workflows/stubs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stubs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  stubs:
+    name: Generate stubs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # attaching the stubs to a tag's release
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          cache: 'gradle'
+
+      - name: Setup Python (for mypy)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Generate the stubs over the Compose jars
+        run: ./gradlew :ksp-fixtures:compose:generatePythonStubs --console=plain
+
+      - name: Type-check a consumer against them (mypy)
+        run: tools/stubs/check-stubs.sh ksp-fixtures/compose/build/generated/pythonStubs/desktopMain
+
+      - name: Assemble the artifact
+        run: |
+          set -euo pipefail
+          compose_version="$(sed -nE 's/^compose-plugin = "([^"]+)".*/\1/p' gradle/libs.versions.toml)"
+          test -n "$compose_version"
+          out=build/kotlin-stubs
+          rm -rf "$out"
+          mkdir -p "$out"
+          cp -R ksp-fixtures/compose/build/generated/pythonStubs/desktopMain/. "$out/"
+          cat > "$out/README.md" <<README
+          # Kotlin-name stubs for Compose ${compose_version}
+
+          \`.pyi\` stubs for the Kotlin declarations the python-multiplatform binder serves, under the
+          **Kotlin** module paths and Kotlin names (\`androidx.compose.material3.Checkbox\`, parameters by
+          their Kotlin names). Nothing here is renamed or Pythonic; that is pythonx-compose's layer.
+
+          | | |
+          |---|---|
+          | Compose | ${compose_version} (desktop jars) |
+          | python-multiplatform commit | ${GITHUB_SHA} |
+          | ref | ${GITHUB_REF} |
+          | workflow run | ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID} |
+          | generator | \`:ksp-fixtures:compose:generatePythonStubs\` |
+
+          Packages stubbed: the \`artifactIncludePackages\` of \`ksp-fixtures/compose/build.gradle.kts\` at
+          that commit.
+
+          Use: put this directory on the type checker's path (\`MYPYPATH=<this directory>\`, or the
+          IDE's "stub path" / interpreter paths). It is checked with mypy against
+          \`tools/stubs/consumer.py\` in the commit above.
+          README
+          (cd build && zip -qr kotlin-stubs.zip kotlin-stubs)
+
+      - name: Upload the stubs
+        uses: actions/upload-artifact@v4
+        with:
+          name: kotlin-stubs
+          path: build/kotlin-stubs
+          if-no-files-found: error
+
+      - name: Attach the stubs to the tag's release
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 \
+            || gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes "Kotlin-name stubs for the Compose version this tag builds against."
+          gh release upload "$GITHUB_REF_NAME" build/kotlin-stubs.zip --clobber
+
+  # Issue #44: the stub layout is case-unique, so the stubs generate, extract and type-check on a
+  # case-insensitive filesystem too (`graphics.Shadow` the class and `graphics.shadow` the package).
+  stubs-macos:
+    name: Generate stubs (macOS, case-insensitive)
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          cache: 'gradle'
+
+      - name: Setup Python (for mypy)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Generate the stubs over the Compose jars
+        run: ./gradlew :ksp-fixtures:compose:generatePythonStubs --console=plain
+
+      - name: No two stub paths are equal under case folding
+        run: |
+          python3 - ksp-fixtures/compose/build/generated/pythonStubs/desktopMain <<'PY'
+          import os, sys
+          seen = {}
+          for root, dirs, files in os.walk(sys.argv[1]):
+              for name in dirs + files:
+                  rel = os.path.relpath(os.path.join(root, name), sys.argv[1])
+                  seen.setdefault(rel.casefold(), []).append(rel)
+          clashes = [v for v in seen.values() if len(v) > 1]
+          print("clashes:", clashes)
+          sys.exit(1 if clashes else 0)
+          PY
+
+      - name: Type-check a consumer against them (mypy)
+        run: tools/stubs/check-stubs.sh ksp-fixtures/compose/build/generated/pythonStubs/desktopMain