codeplain 0.3.8__tar.gz → 0.3.10.dev1__tar.gz

{codeplain-0.3.8 → codeplain-0.3.10.dev1}/.github/workflows/e2e.yml

@@ -59,4 +59,31 @@ jobs:
       - name: Run E2E tests
         env:
           CODEPLAIN_API_KEY: ${{ secrets.CODEPLAIN_API_KEY }}
-        run: pytest tests/e2e/ -v --tb=short
+        run: pytest tests/e2e/ -v --tb=short
+
+  notify-on-failure:
+    name: Notify Slack on failure
+    needs: [e2e-linux, e2e-windows]
+    if: failure()
+    runs-on: ubuntu-latest
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_E2E_WEBHOOK_URL }}
+    steps:
+      - name: Determine failed platforms
+        id: platforms
+        run: |
+          failed=""
+          [ "${{ needs.e2e-linux.result }}" = "failure" ] && failed="Linux"
+          if [ "${{ needs.e2e-windows.result }}" = "failure" ]; then
+            [ -n "$failed" ] && failed="$failed and Windows" || failed="Windows"
+          fi
+          echo "failed=$failed" >> "$GITHUB_OUTPUT"
+
+      - name: Send failure notification to Slack
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        uses: slackapi/slack-github-action@v1.24.0
+        with:
+          payload: |
+            {
+              "text": ${{ toJSON(format('[Codeplain Client] E2E tests FAILED on {0}. See <{1}/{2}/actions/runs/{3}|the run log>.', steps.platforms.outputs.failed, github.server_url, github.repository, github.run_id)) }}
+            }

codeplain-0.3.10.dev1/.github/workflows/lint-powershell.yml

@@ -0,0 +1,124 @@
+name: PowerShell Install Scripts
+
+on:
+  push:
+    paths:
+      - 'install/powershell/*.ps1'
+      - '.github/workflows/lint-powershell.yml'
+  pull_request:
+    paths:
+      - 'install/powershell/*.ps1'
+      - '.github/workflows/lint-powershell.yml'
+  workflow_dispatch:
+
+jobs:
+  parse-windows-powershell-51:
+    name: Parse under Windows PowerShell 5.1
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The install scripts are fetched over HTTP and executed on stock Windows,
+      # where powershell.exe (5.1) is the default shell. 5.1 reads BOM-less files
+      # as ANSI (CP1252), so a non-ASCII glyph such as U+2713 decodes into a smart
+      # quote that silently terminates the enclosing string. The resulting parse
+      # errors point at unrelated lines far below the real cause, so parse every
+      # script with 5.1 explicitly rather than relying on PowerShell 7.
+      - name: Parse each script with 5.1
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Write-Host "PowerShell $($PSVersionTable.PSVersion) / ANSI codepage $([System.Text.Encoding]::Default.WebName)"
+
+          $failed = $false
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $errors = $null
+              [System.Management.Automation.Language.Parser]::ParseFile(
+                  $_.FullName, [ref]$null, [ref]$errors) | Out-Null
+
+              if ($errors -and $errors.Count -gt 0) {
+                  $failed = $true
+                  Write-Host "FAIL $($_.Name): $($errors.Count) parse error(s)"
+                  $errors | Sort-Object { $_.Extent.StartLineNumber } | ForEach-Object {
+                      Write-Host "     L$($_.Extent.StartLineNumber): $($_.Message)"
+                  }
+              } else {
+                  Write-Host "OK   $($_.Name)"
+              }
+          }
+
+          if ($failed) { exit 1 }
+
+      # A BOM would fix file-based parsing but break `irm ... | iex`: PowerShell 5.1
+      # decodes an HTTP text/* body with no charset as ISO-8859-1, turning the BOM
+      # into literal "i>>?" text and failing with
+      # "The term 'i>>?$ErrorActionPreference' is not recognized".
+      # Keeping the sources pure ASCII is what makes both paths safe, so enforce it.
+      - name: Require pure ASCII and no BOM
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $failed = $false
+
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $fileBad = $false
+              $bytes = [System.IO.File]::ReadAllBytes($_.FullName)
+
+              if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
+                  $failed = $true
+                  $fileBad = $true
+                  Write-Host "FAIL $($_.Name): has a UTF-8 BOM (breaks 'irm | iex'); remove it"
+              }
+
+              # Report line/column of any byte outside ASCII so the fix is obvious.
+              $text = [System.Text.Encoding]::UTF8.GetString($bytes)
+              $lineNo = 0
+              foreach ($line in ($text -split "`r?`n")) {
+                  $lineNo++
+                  for ($i = 0; $i -lt $line.Length; $i++) {
+                      if ([int]$line[$i] -gt 127) {
+                          $failed = $true
+                          $fileBad = $true
+                          $cp = "U+{0:X4}" -f [int]$line[$i]
+                          Write-Host "FAIL $($_.Name) L${lineNo} C$($i + 1): non-ASCII $cp"
+                          Write-Host "     build it from its code point instead, e.g. `$CHECK = [char]0x2713"
+                          break
+                      }
+                  }
+              }
+
+              if (-not $fileBad) { Write-Host "OK   $($_.Name)" }
+          }
+
+          if ($failed) { exit 1 }
+
+  parse-powershell-7:
+    name: Parse under PowerShell 7
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Parse each script with 7
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Write-Host "PowerShell $($PSVersionTable.PSVersion)"
+
+          $failed = $false
+          Get-ChildItem 'install/powershell' -Filter *.ps1 | Sort-Object Name | ForEach-Object {
+              $errors = $null
+              [System.Management.Automation.Language.Parser]::ParseFile(
+                  $_.FullName, [ref]$null, [ref]$errors) | Out-Null
+
+              if ($errors -and $errors.Count -gt 0) {
+                  $failed = $true
+                  Write-Host "FAIL $($_.Name): $($errors.Count) parse error(s)"
+                  $errors | Sort-Object { $_.Extent.StartLineNumber } | ForEach-Object {
+                      Write-Host "     L$($_.Extent.StartLineNumber): $($_.Message)"
+                  }
+              } else {
+                  Write-Host "OK   $($_.Name)"
+              }
+          }
+
+          if ($failed) { exit 1 }

codeplain-0.3.10.dev1/.github/workflows/publish-dev-to-pypi.yml

@@ -0,0 +1,135 @@
+name: Publish dev build to PyPI
+
+# Every merge to main publishes a PEP 440 dev release (e.g. 0.3.10.dev7) to
+# PyPI, so the latest main is always installable from the real index with real
+# dependency resolution. Dev releases are pre-releases: pip and uv skip them
+# unless asked, so ordinary installs keep getting the latest stable.
+#
+# Tagged releases (including rc/beta/alpha) are handled by publish-to-pypi.yml.
+on:
+  push:
+    branches: [main]
+  # Ad-hoc runs, e.g. re-publishing after a PyPI outage.
+  workflow_dispatch:
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+# Serialize publishes so versions land in merge order. Queued runs are not
+# cancelled — each merge should still get its own dev build.
+concurrency:
+  group: publish-dev-to-pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build dev distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      should-publish: ${{ steps.version.outputs.should-publish }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Compute dev version
+        id: version
+        # Between releases hatch-vcs produces something like
+        # "0.3.10.dev16+gb710c2982". The "+g..." local version segment is valid
+        # PEP 440 but is rejected by PyPI on upload, so it has to go. We keep
+        # setuptools-scm's own next-version guess (0.3.10 — the patch bump
+        # after the latest tag) rather than re-deriving it here, and use the
+        # run number as the dev counter: it is strictly increasing, so each
+        # merge sorts after the last and re-runs never collide.
+        run: |
+          RAW=$(uvx --from setuptools-scm python -c \
+            "from setuptools_scm import get_version; print(get_version())")
+          echo "setuptools-scm reports: $RAW"
+
+          # On a commit that IS a release tag, setuptools-scm returns a clean
+          # version with no .dev component (e.g. "0.3.9" or "0.4.0rc1").
+          # Appending ".dev<run>" to that yields 0.3.9.dev42, which sorts BELOW
+          # the released 0.3.9 — newer code would look older. A tagged commit
+          # is a real release and is published by publish-to-pypi.yml, so there
+          # is no dev build to make here.
+          case "$RAW" in
+            *.dev*) ;;
+            *)
+              echo "::notice::$RAW is a tagged release; skipping dev build."
+              echo "should-publish=false" >> $GITHUB_OUTPUT
+              exit 0
+              ;;
+          esac
+
+          BASE=${RAW%%+*}
+          BASE=${BASE%%.dev*}
+          VERSION="${BASE}.dev${GITHUB_RUN_NUMBER}"
+          echo "Derived version: $RAW -> $VERSION"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "should-publish=true" >> $GITHUB_OUTPUT
+
+      - name: Build package
+        if: steps.version.outputs.should-publish == 'true'
+        # hatch-vcs reads SETUPTOOLS_SCM_PRETEND_VERSION in place of the tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        if: steps.version.outputs.should-publish == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+  publish-dev:
+    name: Publish dev build to PyPI
+    needs: build
+    if: needs.build.outputs.should-publish == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codeplain
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # PyPI uploads are immutable, so a re-run of an already-published
+          # version should be a no-op, not a red build.
+          skip-existing: true
+
+      # Success is deliberately quiet: this runs on every merge to main, which
+      # is already announced elsewhere. Only failures ping.
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Publishing dev build to PyPI FAILED :x: (commit \`${{ github.sha }}\`). See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

{codeplain-0.3.8 → codeplain-0.3.10.dev1}/.github/workflows/publish-install-script.yml

@@ -14,6 +14,9 @@ jobs:
     name: Upload to Cloudflare R2
     runs-on: ubuntu-latest
 
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
     steps:
       - uses: actions/checkout@v4
 
@@ -54,3 +57,17 @@ jobs:
             --content-type "text/plain"
           echo "✓ examples.ps1 uploaded to R2"
 
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Install scripts deployed to R2 :white_check_mark: (\`${GITHUB_SHA:0:7}\`, by *${{ github.actor }}*).\"}"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Install script deploy to R2 FAILED :x: (\`${GITHUB_SHA:0:7}\`). Users may be getting a stale installer. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+

codeplain-0.3.10.dev1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,117 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Notify Slack (start)
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Release \`${{ github.ref_name }}\` published by *${{ github.actor }}* — building and publishing to PyPI...\"}"
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Build package
+        # hatch-vcs reads the version straight from the release tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Upload assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload ${{ github.ref_name }} dist/* --clobber
+
+      - name: Notify Slack (build failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Build of \`${{ github.ref_name }}\` FAILED :x:. Nothing was published to PyPI. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codeplain
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          # GitHub marks the release itself as a pre-release; the tag
+          # (v0.4.0rc1) carries the same intent for PEP 440.
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          VERSION="${TAG#v}"
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            # pip and uv skip pre-releases by default, so "--upgrade" would
+            # NOT pick this up. Tell people the command that actually works.
+            TEXT="*Codeplain Client*: pre-release \`$TAG\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre codeplain==$VERSION\`."
+          else
+            TEXT="*Codeplain Client*: \`$TAG\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`."
+          fi
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Publishing \`${{ github.ref_name }}\` to PyPI FAILED :x:. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

{codeplain-0.3.8 → codeplain-0.3.10.dev1}/CLAUDE.md

@@ -14,14 +14,14 @@ The codebase serves two audiences:
 - **End users**: developers who write `***plain` specs and run `plain2code.py` to generate code
 - **Internal devs**: maintaining the renderer itself (this codebase)
 
-### Related Repository: plain2code_rest_api
+### Related Repository: codeplain-api
 
-This repository has a sibling repository **`plain2code_rest_api`** which contains the backend API service that this client communicates with. The two repositories are typically cloned as siblings:
+This repository has a sibling repository **`codeplain-api`** which contains the backend API service that this client communicates with. The two repositories are typically cloned as siblings:
 
 ```
 parent-directory/
-├── codeplain/              # This repository (client)
-└── plain2code_rest_api/    # Backend API service
+├── codeplain/          # This repository (client)
+└── codeplain-api/      # Backend API service
 ```
 
 **When to work across both repositories:**
@@ -212,8 +212,12 @@ Two logging modes:
 ### Code Generation Process
 - Templates in `standard_template_library/` use Liquid2 syntax
 - Template search order: (1) `.plain` file dir, (2) `--template-dir`, (3) built-in standard lib
-- Generated code written to `build/` (configurable via `--build-folder`)
-- Each FRID render produces a git commit in build folder for rollback capability
+- Each module renders into its own tree under the build folder (configurable via `--build-folder`, default `plain_modules/`):
+  - `<build-folder>/<module>/code/` — implementation code (its own git repo)
+  - `<build-folder>/<module>/tests/` — conformance tests (its own git repo; only created when a conformance tests script is configured)
+  - `<build-folder>/<module>/.codeplain/` — module metadata (`module_metadata.json`), not tracked in git
+  - `<build-folder>/<module>/.memory/` — conformance test memory, not tracked in git
+- Each FRID render produces a git commit in the `code/` and `tests/` repos for rollback capability
 
 ### Configuration
 - `config.yaml` can be placed in `.plain` file dir or CWD

codeplain-0.3.10.dev1/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to Codeplain
+
+Thanks for contributing to Codeplain.
+
+## Before You Start
+
+Check existing issues and pull requests before starting work.
+
+Keep each contribution focused on one issue or a closely related set of changes.
+
+## Contribution Workflow
+
+1. Fork the Codeplain repository.
+2. Make your changes on a branch in your fork.
+3. Commit and push the changes to your fork.
+4. Open a pull request against the Codeplain `main` branch.
+
+## Configure Codeplain
+
+Use your own Codeplain API key for local development and testing.
+
+Never commit API keys, credentials, or other secrets.
+
+## Test with a Plain Example
+
+When relevant, test your change with an existing example from the `plainlang-examples` repository.
+
+This provides a real `.plain` project for verifying the change in an actual Codeplain workflow.
+
+## Run Tests
+
+Run the tests relevant to your change before opening a pull request.
+
+For changes that affect the CLI, rendering, or test execution, also test the change by running the relevant Codeplain command from the terminal.
+
+Check that:
+
+* the command returns the expected exit code,
+* errors are clear and do not expose unintended tracebacks,
+* existing Codeplain behavior still works.
+
+For platform-specific changes, test the relevant `.sh` or `.ps1` workflow.
+
+## Keep the Change Clean
+
+Before submitting:
+
+* remove temporary files and debugging output,
+* avoid unrelated changes,
+* add or update tests where needed,
+* update documentation when behavior changes,
+* verify that no secrets are included.
+
+Review your changes with:
+
+```bash
+git status
+git diff
+```
+
+## Pull Request
+
+Include:
+
+* what changed,
+* why it changed,
+* the related issue, when applicable,
+* how the change was tested,
+* the `plainlang-examples` example used, when relevant.
+
+## Pre-Releases
+
+Everything below happens on real PyPI — there is no separate test index.
+Pre-releases are invisible to ordinary installs: pip and uv skip them during
+resolution, so `pip install codeplain` and `pip install --upgrade codeplain`
+always serve the latest *stable* release.
+
+### Dev builds (automatic)
+
+Every merge to `main` publishes a dev release such as `0.3.10.dev7`, so the tip
+of main is always installable from the real index:
+
+```bash
+pip install --pre codeplain==0.3.10.dev7
+uv tool install --prerelease allow codeplain
+```
+
+Versions are `<next-patch>.dev<run-number>`, so they sort after the last
+release and before the next one. See `.github/workflows/publish-dev-to-pypi.yml`.
+If that workflow is ever dispatched against a commit that is itself a release
+tag, it skips rather than publishing a dev build that would sort below the
+release.
+
+### Release candidates (manual)
+
+To get a specific build in front of people before it becomes the default
+install, cut a PEP 440 pre-release.
+
+Tag and publish a GitHub release as usual, but with a pre-release version and
+the release marked "pre-release":
+
+```
+v0.4.0a1    alpha
+v0.4.0b1    beta
+v0.4.0rc1   release candidate
+```
+
+`publish-to-pypi.yml` handles these with no special casing: hatch-vcs reads the
+version straight off the tag (`v0.4.0rc1` -> `0.4.0rc1`).
+
+Opt in the same way:
+
+```bash
+pip install --pre codeplain==0.4.0rc1
+```
+
+### Which API a build talks to
+
+Pre-release builds default to the **test** API, so an unreleased client is
+exercised against the unreleased backend:
+
+| build | default API |
+| --- | --- |
+| stable release (`0.3.9`) | `https://api.codeplain.ai` |
+| dev build (`0.3.10.dev7`) | `https://api.test.codeplain.ai` |
+| alpha/beta/rc (`0.4.0rc1`) | `https://api.test.codeplain.ai` |
+
+`--api` always overrides this. Resolution lives in
+`system_config._resolve_default_api_url`, keyed off the version baked into the
+package at build time — so nothing needs configuring at install time.
+
+A source checkout reports the nearest git tag as its version, so it is treated
+as stable and keeps pointing at production; use `--api` to aim it elsewhere.
+
+Because every build above goes to real PyPI, dependency resolution and the
+install path are exactly what an end user gets — the main reason this is
+preferred over publishing to TestPyPI.