release: 0.1.0

.devcontainer/Dockerfile

@@ -0,0 +1,9 @@
+ARG VARIANT="3.9"
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}
+
+USER vscode
+
+RUN curl -sSf https://rye.astral.sh/get | RYE_VERSION="0.44.0" RYE_INSTALL_OPTION="--yes" bash
+ENV PATH=/home/vscode/.rye/shims:$PATH
+
+RUN echo "[[ -d .venv ]] && source .venv/bin/activate || export PATH=\$PATH" >> /home/vscode/.bashrc

.devcontainer/devcontainer.json

@@ -0,0 +1,43 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+  "name": "Debian",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+
+  "postStartCommand": "rye sync --all-features",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python"
+      ],
+      "settings": { 
+        "terminal.integrated.shell.linux": "/bin/bash",
+        "python.pythonPath": ".venv/bin/python",
+        "python.defaultInterpreterPath": ".venv/bin/python",
+        "python.typeChecking": "basic",
+        "terminal.integrated.env.linux": {
+          "PATH": "/home/vscode/.rye/shims:${env:PATH}"
+        }
+      }
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {}
+  }
+
+  // Features to add to the dev container. More info: https://containers.dev/features.
+  // "features": {},
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
+
+  // Configure tool-specific properties.
+  // "customizations": {},
+
+  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+  // "remoteUser": "root"
+}

.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+on:
+  push:
+    branches:
+      - '**'
+      - '!integrated/**'
+      - '!stl-preview-head/**'
+      - '!stl-preview-base/**'
+      - '!generated'
+      - '!codegen/**'
+      - 'codegen/stl/**'
+  pull_request:
+    branches-ignore:
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
+
+jobs:
+  lint:
+    timeout-minutes: 10
+    name: lint
+    runs-on: ubuntu-latest
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> $GITHUB_PATH
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+
+      - name: Install dependencies
+        run: rye sync --all-features
+
+      - name: Run lints
+        run: ./scripts/lint
+
+      - name: Run tests
+        run: ./scripts/test
+
+  build:
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
+    timeout-minutes: 10
+    name: build
+    permissions:
+      contents: read
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> $GITHUB_PATH
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+
+      - name: Install dependencies
+        run: rye sync --all-features
+
+      - name: Run build
+        run: rye build

.github/workflows/publish-pypi.yml

@@ -0,0 +1,37 @@
+# This workflow is triggered when a GitHub release is created.
+# It can also be run manually to re-publish to PyPI in case it failed for some reason.
+# You can run this workflow by navigating to https://www.github.com/kernel/hypeman-python/actions/workflows/publish-pypi.yml
+name: Publish PyPI
+on:
+  workflow_dispatch:
+
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hypeman
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Rye
+        run: |
+          curl -sSf https://rye.astral.sh/get | bash
+          echo "$HOME/.rye/shims" >> $GITHUB_PATH
+        env:
+          RYE_VERSION: '0.44.0'
+          RYE_INSTALL_OPTION: '--yes'
+
+      - name: Build distributions
+        run: rye build --clean
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

.github/workflows/release-doctor.yml

@@ -0,0 +1,22 @@
+name: Release Doctor
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  release_doctor:
+    name: release doctor
+    runs-on: ubuntu-latest
+    if: github.repository == 'kernel/hypeman-python' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Check release environment
+        run: |
+          bash ./bin/check-release-environment
+        env:
+          ADMIN_APP_ID: ${{ secrets.ADMIN_APP_ID }}
+          ADMIN_APP_PRIVATE_KEY: ${{ secrets.ADMIN_APP_PRIVATE_KEY }}

.github/workflows/stlc-promote.yml

@@ -0,0 +1,158 @@
+name: Promote SDK changes
+
+# Staging is the generator's integration history. Production `next` is the
+# developer-facing queue for the next release. This workflow combines the
+# latest released state with validated staging changes, then advances `next`.
+# Release automation maintains the single versioned PR from `next` to `main`.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  promote:
+    if: github.repository == 'kernel/hypeman-python-staging'
+    runs-on: ${{ vars.STLC_RUNNER || 'ubuntu-latest' }}
+    concurrency:
+      group: stlc-promote
+      cancel-in-progress: true
+    steps:
+      - name: Check out staging
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Mint production token
+        id: production-token
+        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+        with:
+          app-id: ${{ secrets.ADMIN_APP_ID }}
+          private-key: ${{ secrets.ADMIN_APP_PRIVATE_KEY }}
+          owner: kernel
+          repositories: hypeman-python
+          permission-contents: write
+          permission-pull-requests: write
+          permission-workflows: write
+
+      - name: Fetch production branches
+        id: production
+        env:
+          GH_TOKEN: ${{ steps.production-token.outputs.token }}
+          PRODUCTION_REPO: kernel/hypeman-python
+        run: |
+          set -euo pipefail
+          git remote add production \
+            "https://x-access-token:${GH_TOKEN}@github.com/${PRODUCTION_REPO}.git"
+          if git ls-remote --exit-code --heads production main >/dev/null 2>&1; then
+            git fetch production main
+            echo "has_main=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_main=false" >> "$GITHUB_OUTPUT"
+          fi
+          if git ls-remote --exit-code --heads production next >/dev/null 2>&1; then
+            git fetch production next
+            echo "has_next=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_next=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Prepare the next release branch
+        env:
+          APP_SLUG: ${{ steps.production-token.outputs.app-slug }}
+          GH_TOKEN: ${{ steps.production-token.outputs.token }}
+          HAS_MAIN: ${{ steps.production.outputs.has_main }}
+          HAS_NEXT: ${{ steps.production.outputs.has_next }}
+          PRODUCTION_REPO: kernel/hypeman-python
+        run: |
+          set -euo pipefail
+          bot_id=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)
+          git config user.name "${APP_SLUG}[bot]"
+          git config user.email "${bot_id}+${APP_SLUG}[bot]@users.noreply.github.com"
+
+          open_conflict_pr() {
+            source_ref=$1
+            source_name=$2
+            advance_next=$3
+            conflict_branch=stlc/promotion-conflict
+
+            git merge --abort
+            existing=$(gh pr list --repo "$PRODUCTION_REPO" --base next \
+              --head "$conflict_branch" --state open --json url --jq '.[0].url // ""')
+            if [ -n "$existing" ]; then
+              echo "::error title=SDK promotion blocked::Resolve the existing recovery PR: $existing"
+              exit 1
+            fi
+
+            if [ "$advance_next" = "true" ]; then
+              git push production HEAD:refs/heads/next
+            fi
+            git push production "$source_ref:refs/heads/$conflict_branch" --force
+
+            body=$(mktemp)
+            printf '%s\n' \
+              '## SDK promotion conflict' \
+              '' \
+              "The automated promotion could not merge $source_name into the pending next release." \
+              '' \
+              'Resolve the conflicts on this branch, validate the SDK, mark this PR ready, and merge it with a merge commit.' \
+              '' \
+              'After merging, rerun the staging Promote SDK changes workflow to include any newer generated changes.' \
+              > "$body"
+            recovery_url=$(gh pr create --repo "$PRODUCTION_REPO" --draft \
+              --base next --head "$conflict_branch" \
+              --title 'chore: resolve SDK promotion conflict' --body-file "$body")
+            echo "::error title=SDK promotion conflict::Resolve the recovery PR: $recovery_url"
+            exit 1
+          }
+
+          if [ "$HAS_MAIN" != "true" ]; then
+            # The Python production repository started empty. Seed a minimal
+            # default branch so release-please can open the first next -> main
+            # release PR while preserving staging as a parent of that release.
+            git checkout --orphan stlc/bootstrap-main
+            git rm -rf .
+            git checkout origin/main -- \
+              .github/workflows/release-please.yml \
+              .release-please-manifest.json \
+              release-please-config.json
+            git commit -m 'chore: initialize SDK release history'
+            git push production HEAD:refs/heads/main
+            git fetch production main
+          fi
+
+          if [ "$HAS_NEXT" = "true" ]; then
+            git checkout -B stlc/promote-next production/next
+          else
+            git checkout -B stlc/promote-next production/main
+          fi
+
+          if ! git merge-base --is-ancestor production/main HEAD; then
+            if ! git merge --no-edit production/main; then
+              open_conflict_pr production/main 'production main' false
+            fi
+          fi
+          if ! git merge-base --is-ancestor origin/main HEAD; then
+            merge_args=(--no-edit)
+            if ! git merge-base production/main origin/main >/dev/null 2>&1; then
+              merge_args+=(--allow-unrelated-histories)
+            fi
+            if ! git merge "${merge_args[@]}" origin/main; then
+              open_conflict_pr origin/main 'validated staging changes' true
+            fi
+          fi
+
+          if [ "$HAS_NEXT" = "true" ]; then
+            git merge-base --is-ancestor production/next HEAD
+          fi
+
+      - name: Update the pending release
+        env:
+          GH_TOKEN: ${{ steps.production-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          git push production HEAD:refs/heads/next
+          echo "Updated production next; the versioned release PR will be opened or refreshed."