release.yml

name: Release

# Triggered from the Actions "Run workflow" UI. A pushed tag is no
# longer the trigger: the GitHub Releases UI cannot drive the
# draft-first immutable publish flow (a draft release never creates a
# tag, so no push event fires). Publishing jobs (npm, pypi, vscode,
# release) declare `environment: release` and are gated behind its
# required-reviewer rule; preflight and build run without that gate.
# The `release` job creates the tag itself. See
# docs/development/release.md.
on:
  workflow_dispatch:
    inputs:
      version:
        description: "Release version, e.g. v0.13.0 (must start with v)"
        required: true
        type: string

permissions:
  contents: read

env:
  VERSION: ${{ inputs.version }}

# Serialize release runs so two publish jobs cannot mint OIDC tokens
# against the same registry at the same time. `cancel-in-progress:
# false` keeps the first release going (cancelling mid-publish would
# leave the scoped platform packages out of sync with the root
# package).
concurrency:
  group: release
  cancel-in-progress: false

jobs:
  # Validate the tag before any credential-bearing job runs. The tag
  # is read through an env var, never interpolated into the shell, so
  # a crafted value cannot inject commands (zizmor template-expansion
  # rule). This job also carries the repository guard anchor reused by
  # every publishing job.
  preflight:
    runs-on: ubuntu-latest
    if: &release_repo_trigger_ok >-
      github.repository == 'jeduden/mdsmith'
    steps:
      - name: Validate version tag
        env:
          INPUT_VERSION: ${{ inputs.version }}
        run: |
          if ! printf '%s' "$INPUT_VERSION" | \
            grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+([-.+][0-9A-Za-z.-]+)?$'; then
            echo "version must look like v1.2.3 (got '$INPUT_VERSION')" >&2
            exit 1
          fi
          echo "release version: $INPUT_VERSION"

  build:
    needs: [preflight]
    if: *release_repo_trigger_ok
    strategy:
      matrix:
        include:
          - goos: linux
            goarch: amd64
          - goos: linux
            goarch: arm64
          - goos: darwin
            goarch: amd64
          - goos: darwin
            goarch: arm64
          - goos: windows
            goarch: amd64
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - name: Build
        env:
          GOOS: ${{ matrix.goos }}
          GOARCH: ${{ matrix.goarch }}
          # Disable cgo so the native linux/amd64 build resolves
          # net and os/user purely in Go. Cross-compiles already
          # auto-disable CGO; the native build would otherwise
          # bind glibc's resolver into the binary, breaking the
          # manylinux_2_17 wheel and the @mdsmith/linux-x64 npm
          # package on Alpine/musl and on systems whose glibc is
          # older than the wheel tag claims. macOS and Windows
          # binaries still link the platform syscall layer
          # (libSystem, kernel32) — this knob is about avoiding
          # glibc on Linux, not achieving full static linkage.
          CGO_ENABLED: "0"
          VERSION: ${{ env.VERSION }}
        run: |
          ext=""
          if [ "$GOOS" = "windows" ]; then ext=".exe"; fi
          bin="mdsmith-${GOOS}-${GOARCH}${ext}"
          go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o "$bin" ./cmd/mdsmith
          echo "bin=$bin" >> "$GITHUB_ENV"
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: mdsmith-${{ matrix.goos }}-${{ matrix.goarch }}
          path: ${{ env.bin }}

  vscode:
    # `needs: [build]` for the binaries: the .vsix bundles a binary
    # for *every* supported platform (build.ts → dist/cli/), so the
    # extension picks the right one at runtime by re-using the
    # @mdsmith/cli resolver. The five binaries come straight from the
    # `build` job's release artifacts via `mdsmith-release build-npm`
    # — the same generator the `npm` job uses — so this job no longer
    # waits on (or couples to) the npm publish.
    needs: [build]
    runs-on: ubuntu-latest
    # MDSMITH_VSIX_PLATFORM_DIR points build.ts at the full
    # build-npm output. It is set at job scope so the run that
    # `vsce package` triggers through the `vscode:prepublish` hook
    # re-stages all five binaries too (build.ts staging is also
    # non-destructive, so a missing env would keep — not wipe — the
    # explicit build's binaries; the env makes it deterministic).
    env:
      MDSMITH_VSIX_PLATFORM_DIR: ${{ github.workspace }}/npm/dist
    # VSCE_PAT and OVSX_PAT are long-lived publisher tokens — see
    # docs/development/release.md for why the `release` environment
    # gates them and what reviewer rules the maintainer should set
    # on it.
    if: *release_repo_trigger_ok
    environment: release
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-bun
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          # zizmor's cache-poisoning rule treats the GitHub Actions
          # tool cache as an unprotected mutation surface in
          # release-context workflows; setup-go would default to
          # caching the module download. Disable it to match the
          # build job above.
          cache: false
      - name: Stamp tracked manifests with the tag
        env:
          VERSION: ${{ env.VERSION }}
        # Stamp rewrites the `version` field in
        # editors/vscode/package.json (the .vsix version) and the
        # one in npm/mdsmith/package.json that build-npm stamps
        # into each generated platform manifest.
        run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
      - name: Download release artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          path: artifacts
          merge-multiple: true
      - name: Build platform packages
        # Reuse the npm generator so the .vsix carries the exact
        # same per-platform binaries the npm channel ships. Output
        # lands in npm/dist/<target>/bin/, which
        # MDSMITH_VSIX_PLATFORM_DIR points build.ts at.
        run: go run ./cmd/mdsmith-release build-npm artifacts npm/dist
      - name: Install extension dependencies
        working-directory: editors/vscode
        # `--ignore-scripts` blocks postinstall / preinstall hooks from
        # every dep in the resolved tree. The mdsmith extension's
        # production deps (vscode-languageclient) and dev deps
        # (@vscode/vsce, typescript, @types/*) are pure-JS and need
        # no install-time hooks — disabling them shrinks the blast
        # radius if a future lockfile update or registry compromise
        # ships a malicious lifecycle script (the TanStack /
        # shai-hulud worm class).
        #
        # No `--frozen-lockfile` here: the Stamp step above just
        # rewrote the @mdsmith/cli optionalDependency to the
        # version this run is publishing, so bun.lock is
        # intentionally out-of-date for that one entry.
        # `--ignore-scripts` still guards the lifecycle-hook
        # surface that the shai-hulud / TanStack worm relies on.
        run: bun install --ignore-scripts
      - name: Run extension unit tests
        working-directory: editors/vscode
        run: bun test
      - name: Compile extension
        working-directory: editors/vscode
        run: bun run build.ts --production
      - name: Package .vsix
        env:
          VERSION: ${{ env.VERSION }}
        working-directory: editors/vscode
        run: |
          ver="${VERSION#v}"
          bunx --bun @vscode/vsce package --no-dependencies \
            --out "mdsmith-${ver}.vsix"
      # Verify the publisher tokens are set BEFORE the publish steps
      # run. The publishes themselves use `continue-on-error: true`
      # so a transient registry outage does not block the GitHub
      # release. That same flag would also hide an unset/empty
      # secret, so guard misconfiguration here (no continue-on-error)
      # while still letting outages slide on the actual publish.
      - name: Verify Marketplace and Open VSX tokens are set
        env:
          VSCE_PAT: ${{ secrets.VSCE_PAT }}
          OVSX_PAT: ${{ secrets.OVSX_PAT }}
        run: |
          missing=""
          [ -n "${VSCE_PAT:-}" ] || missing="$missing VSCE_PAT"
          [ -n "${OVSX_PAT:-}" ] || missing="$missing OVSX_PAT"
          if [ -n "$missing" ]; then
            echo "missing required repo secret(s):$missing" >&2
            exit 1
          fi
      - name: Publish to Visual Studio Marketplace
        # The GitHub release .vsix is the documented fallback, so a
        # transient Marketplace outage should not block the release
        # job downstream of this one. Misconfiguration is caught by
        # the preceding verify step, so this only swallows runtime
        # registry errors.
        continue-on-error: true
        env:
          VERSION: ${{ env.VERSION }}
          VSCE_PAT: ${{ secrets.VSCE_PAT }}
        working-directory: editors/vscode
        # Reuse the exact .vsix the artifact upload below ships, so
        # Marketplace, Open VSX, and the GitHub release are byte-
        # identical. The publisher namespace is jeduden — claim it
        # in https://aka.ms/vscode-create-publisher before the first
        # release. PAT scope: Marketplace > Manage. Azure caps PATs
        # at one year; rotate annually and record the date in
        # CLAUDE.md.
        run: |
          ver="${VERSION#v}"
          bunx --bun @vscode/vsce publish \
            --no-dependencies \
            --packagePath "mdsmith-${ver}.vsix" \
            --pat "$VSCE_PAT"
      - name: Publish to Open VSX
        continue-on-error: true
        env:
          VERSION: ${{ env.VERSION }}
          OVSX_PAT: ${{ secrets.OVSX_PAT }}
        working-directory: editors/vscode
        # Open VSX is the registry VSCodium, Cursor, Theia, and
        # Gitpod query. Claim the jeduden namespace on
        # https://open-vsx.org and store the publisher token as the
        # OVSX_PAT secret before the first release. Rotate annually.
        run: |
          ver="${VERSION#v}"
          bunx --bun ovsx publish \
            --packagePath "mdsmith-${ver}.vsix" \
            --pat "$OVSX_PAT"
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: mdsmith-vscode-extension
          path: editors/vscode/mdsmith-*.vsix

  obsidian:
    # Plan 217. The Obsidian plugin ships ONE WASM artifact (not a
    # per-platform binary), so it does not depend on the `build` matrix.
    # It compiles the engine to WebAssembly, builds the plugin, and zips
    # dist/ as mdsmith-obsidian-<version>.zip. The `release` job
    # downloads it with the other artifacts and the `mdsmith-*` globs
    # there cover it for the GitHub release attachment, the checksum
    # file, the SLSA provenance, and the cosign signature.
    #
    # No publisher tokens and no `release` environment: the only channel
    # is GitHub Releases (plan 217 Non-Goals), so there is nothing to
    # gate. The plugin manifests (editors/obsidian/{manifest,package}.json)
    # are in the tracked-manifest set, so `mdsmith-release stamp` rewrites
    # their dev sentinel to the release version alongside the rest of the
    # tracked set; only this job's zip carries the result.
    needs: [preflight]
    if: *release_repo_trigger_ok
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup-bun
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - name: Stamp the manifests with the release version
        env:
          VERSION: ${{ env.VERSION }}
        # Runtime logic lives in mdsmith-release per
        # docs/development/release-tooling.md. stamp rewrites every
        # tracked manifest's dev sentinel to the release tag (the obsidian
        # manifest.json/package.json among them); the checkout is
        # discarded after the run, so only the zip built below ships the
        # stamped files.
        run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
      - name: Install plugin dependencies
        working-directory: editors/obsidian
        # --ignore-scripts neutralizes install-time hooks (see the npm
        # job and release.md). No --frozen-lockfile: the stamp above
        # rewrote package.json's version, so bun.lock is intentionally
        # out of date for that field.
        run: bun install --ignore-scripts
      - name: Run plugin unit tests
        working-directory: editors/obsidian
        run: bun test --preload ./src/test-setup.ts
      - name: Build the engine to WebAssembly
        run: bash cmd/mdsmith-wasm/build.sh
      - name: Build the plugin
        working-directory: editors/obsidian
        env:
          MDSMITH_OBSIDIAN_WASM_DIR: ${{ github.workspace }}/cmd/mdsmith-wasm/dist
        run: bun run build.ts --production
      - name: Package the release zip
        # Runtime logic lives in mdsmith-release per
        # docs/development/release-tooling.md. The stamp step above
        # rewrote dist's manifest.json to the release version, so
        # package-obsidian reads the version from there and writes
        # mdsmith-obsidian-<version>.zip with the five files Obsidian
        # loads, flat, via archive/zip. outDir is editors/obsidian so
        # the upload glob below matches.
        run: go run ./cmd/mdsmith-release package-obsidian editors/obsidian/dist editors/obsidian
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: mdsmith-obsidian-plugin
          path: editors/obsidian/mdsmith-obsidian-*.zip

  npm:
    needs: [build]
    runs-on: ubuntu-latest
    # See docs/development/release.md for the canonical description
    # of `if:`, `environment:`, OIDC Trusted Publishing scope, and
    # the operational checklist for npmjs.com / pypi.org / GitHub
    # environment configuration. Workflow comments here only record
    # the local intent of each setting.
    if: *release_repo_trigger_ok
    environment: release
    # `id-token: write` lets `npm publish --provenance` mint an OIDC
    # token so the npm registry stamps each tarball with verifiable
    # build metadata pointing at this exact workflow run.
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          # Node 24 ships npm 11.x. npm Trusted Publishing
          # requires npm >= 11.5; older CLIs silently fall back
          # to token auth and the registry returns 404 for
          # missing-credential publishes (404 instead of 401 so
          # package existence isn't leaked).
          node-version: "24"
          registry-url: "https://registry.npmjs.org"
      - name: Verify npm >= 11.5 for Trusted Publishing
        # Defensive guardrail: even though Node 24 currently ships
        # npm 11.x, a future Node 24 patch could bundle an older
        # CLI. If npm < 11.5 the publish would silently 404.
        run: |
          actual=$(npm --version)
          echo "npm version: $actual"
          node -e '
            const v = process.argv[1].split(".").map(Number);
            const min = [11, 5, 0];
            for (let i = 0; i < 3; i++) {
              if (v[i] > min[i]) process.exit(0);
              if (v[i] < min[i]) {
                console.error("npm " + process.argv[1] +
                  " is too old for Trusted Publishing (need >= 11.5.0)");
                process.exit(1);
              }
            }
          ' "$actual"
      - name: Stamp tracked manifests with the tag
        env:
          VERSION: ${{ env.VERSION }}
        run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
      - name: Download release artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          path: artifacts
          merge-multiple: true
      - name: Build platform packages
        run: go run ./cmd/mdsmith-release build-npm artifacts npm/dist
      - name: Publish platform packages
        # Platform packages publish first so the root never advertises
        # an optionalDependency npm cannot find. The root package
        # publishes last, after every platform exists. Auth uses npm
        # Trusted Publishing (OIDC) — see docs/development/release.md
        # for the npmjs.com publisher configuration each of the six
        # packages needs.
        run: |
          for pkg in npm/dist/*; do
            (cd "$pkg" && npm publish --access public --provenance)
          done
      - name: Stage LICENSE for root package
        # The root @mdsmith/cli package directory has no checked-in
        # LICENSE because the canonical one lives at repo root. npm
        # auto-includes a top-level LICENSE in the published tarball,
        # but only if it sits next to package.json at publish time —
        # so copy it in before `npm publish`. The root LICENSE also
        # carries the vendored neurosnap/sentences MIT notice for
        # internal/punkt/, which is what makes this step legally
        # required for the npm channel.
        run: cp LICENSE npm/mdsmith/LICENSE
      - name: Publish root package
        working-directory: npm/mdsmith
        run: npm publish --access public --provenance

  pypi:
    needs: [build]
    runs-on: ubuntu-latest
    # See docs/development/release.md for the canonical PyPI Trusted
    # Publisher config (workflow + environment scope) and the
    # operational checklist.
    if: *release_repo_trigger_ok
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.12"
      - name: Stamp tracked manifests with the tag
        env:
          VERSION: ${{ env.VERSION }}
        run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
      - name: Install build tooling
        # `python -m build` and `python -m wheel` orchestrate the
        # wheel build and the platform-tag retag respectively;
        # hatchling is the build backend pyproject.toml selects.
        run: python -m pip install --upgrade build wheel hatchling
      - name: Download release artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          path: artifacts
          merge-multiple: true
      - name: Build platform wheels
        run: go run ./cmd/mdsmith-release build-wheels artifacts python/dist
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
        with:
          packages-dir: python/dist

  release:
    # `flatpak` joins `build`/`vscode` here so the .flatpak bundle it
    # produces is downloaded with the other artifacts and uploaded to
    # the draft before it freezes. The bundle is named with the
    # `mdsmith-` prefix, so the checksum, SLSA attestation, and cosign
    # steps below cover it via the same `mdsmith-*` glob as the raw
    # binaries — no release-job changes beyond this dependency. `obsidian`
    # (plan 217) joins for the same reason: its
    # mdsmith-obsidian-<version>.zip is matched by the `mdsmith-*` globs.
    needs: [build, vscode, obsidian, flatpak]
    runs-on: ubuntu-latest
    # See docs/development/release.md for the rationale on `if:`,
    # `environment:`, and the OIDC + attestations permission set.
    if: *release_repo_trigger_ok
    environment: release
    permissions:
      contents: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          merge-multiple: true
      - name: Generate CycloneDX SBOM
        # CycloneDX SBOM of the Go module that produced the release
        # binaries. Runtime logic lives in mdsmith-release per
        # docs/development/release-tooling.md: the tool version is
        # pinned in internal/release/sbom.go and the implementation
        # uses `go run <module>@<pinned>` so no PATH setup beyond
        # the Go toolchain is required. Output is named with the
        # `mdsmith-` prefix so the checksum step below picks it up
        # automatically and the cosign signature covers it
        # transitively. Verify with:
        #   sha256sum -c <(grep mdsmith-sbom.cdx.json checksums.txt)
        run: go run ./cmd/mdsmith-release sbom mdsmith-sbom.cdx.json
      - name: Create checksums
        run: sha256sum mdsmith-* > checksums.txt
      - name: Generate SLSA build provenance
        # Attests every binary the build matrix produced (and the
        # .vsix the vscode job uploaded — `mdsmith-*` matches both).
        # Each attestation ties the file's SHA-256 back to this
        # workflow run and the commit it was built from. Consumers
        # verify with:
        #   gh attestation verify mdsmith-<plat> -R jeduden/mdsmith
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-path: "mdsmith-*"
      - name: Install cosign
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
        with:
          # Pin cosign to a known v3.x release. The sign-blob step
          # below relies on `--bundle` being the required output
          # path (cosign 3.0.0 promoted it from optional to
          # required); pinning shields the release from a future
          # installer default rolling forward to a major that
          # changes the bundle contract again.
          cosign-release: "v3.0.6"
      - name: Sign checksums with cosign
        # Keyless Sigstore signature on the checksum file. The
        # GitHub OIDC token binds the signature to this exact
        # workflow file at this exact tag, so an attacker who
        # rewrites checksums.txt on the release page can't also
        # forge a matching signature without compromising
        # release.yml on this repo. The bundle file carries both
        # the signature and the signing certificate; cosign 3.x
        # deprecated the separate --output-signature /
        # --output-certificate flags in favor of --bundle.
        # Verify with:
        #   cosign verify-blob \
        #     --bundle checksums.txt.bundle \
        #     --certificate-identity-regexp \
        #       "^https://github.com/jeduden/mdsmith/.github/workflows/release.yml@" \
        #     --certificate-oidc-issuer \
        #       https://token.actions.githubusercontent.com \
        #     checksums.txt
        env:
          COSIGN_YES: "true"
        run: |
          cosign sign-blob \
            --bundle checksums.txt.bundle \
            checksums.txt
      - name: Upload assets to draft release
        # Create the release as a draft so every asset uploads while
        # the release is still mutable. With immutable releases
        # enforced, uploading to an already-published release is
        # rejected — the publish must be the final step.
        #
        # The workflow is dispatched from a branch, not a tag, so the
        # tag does not exist yet: `tag_name` + `target_commitish`
        # make this step create it at the dispatched commit.
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
        with:
          draft: true
          tag_name: ${{ env.VERSION }}
          target_commitish: ${{ github.sha }}
          generate_release_notes: true
          files: |
            mdsmith-*
            checksums.txt
            checksums.txt.bundle
      - name: Publish release
        # Flip the fully-populated draft to published as the final
        # atomic step, yielding an immutable release. Runtime logic
        # lives in mdsmith-release per
        # docs/development/release-tooling.md.
        env:
          RELEASE_TAG: ${{ env.VERSION }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: go run ./cmd/mdsmith-release publish-release

  # Build the self-hosted .flatpak bundle. Like `vscode`, this chains
  # off `build` (not `release`) and hands its artifact to the `release`
  # job, which attaches `mdsmith-x86_64.flatpak` to the draft before it
  # freezes — uploading to an immutable, already-published release is
  # rejected. The bundle is built from the freshly built x86_64 binary
  # via flatpak-builder, so it needs no published download URL. x86_64
  # only: flatpak-builder targets the runner's native arch and
  # cross-building aarch64 under emulation is not worth it for this
  # channel (aarch64 Linux uses the binary, npm, or PyPI channels).
  # The job carries no secrets, so it runs without the `release`
  # environment gate. See docs/development/release-channels/flatpak.md.
  flatpak:
    needs: [build]
    runs-on: ubuntu-latest
    # Bound the heavy steps (apt install + ~hundreds-of-MB Flathub
    # runtime pull + flatpak-builder) so a stuck download cannot hold
    # the release-gating job to the 6h default.
    timeout-minutes: 20
    if: *release_repo_trigger_ok
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
        with:
          go-version-file: go.mod
          cache: false
      - name: Download release artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          path: artifacts
          merge-multiple: true
      - name: Stage manifest and binaries
        # build-flatpak writes the flatpak-builder manifest and copies
        # the Linux binaries it references (via local `path:` sources)
        # into flatpak-build/, so the bundle builds without a release
        # download URL.
        run: go run ./cmd/mdsmith-release build-flatpak artifacts flatpak-build
      - name: Install flatpak-builder and the freedesktop runtime
        run: |
          sudo apt-get update
          sudo apt-get install -y flatpak flatpak-builder
          # Ubuntu 24.04 restricts unprivileged user namespaces via
          # AppArmor, which blocks the bubblewrap sandbox that
          # flatpak-builder and `flatpak run` rely on. Re-enable it on
          # the runner (best-effort: the knob is absent on older
          # kernels, where the restriction does not exist).
          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 || true
          flatpak remote-add --user --if-not-exists \
            flathub https://flathub.org/repo/flathub.flatpakrepo
      - name: Build the bundle
        # flatpak-builder pulls the org.freedesktop 24.08 Platform/SDK
        # from flathub, builds the app into a local OSTree repo, and
        # build-bundle packs it into a single file. --runtime-repo
        # records flathub so `flatpak install ./mdsmith-x86_64.flatpak`
        # can offer the runtime if the host lacks it.
        # --disable-rofiles-fuse avoids the rofiles-fuse mount, which is
        # fragile under the runner's restricted FUSE.
        run: |
          flatpak-builder --user --install-deps-from=flathub \
            --disable-rofiles-fuse --force-clean --repo=flatpak-repo \
            flatpak-build-dir flatpak-build/io.github.jeduden.mdsmith.yml
          flatpak build-bundle \
            --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo \
            flatpak-repo mdsmith-x86_64.flatpak io.github.jeduden.mdsmith
      - name: Verify the bundle installs and reports the right version
        # No other job exercises this channel (smoke-test runs in
        # flatpak-less containers), so confirm the bundle installs and
        # `mdsmith version` matches the tag before it ships. A broken
        # bundle fails the job — and, since `release` needs it, blocks
        # the release rather than shipping a dud asset.
        env:
          VERSION: ${{ env.VERSION }}
        run: |
          flatpak install --user -y ./mdsmith-x86_64.flatpak
          # Take the last stdout line so a first-run portal/sandbox
          # notice cannot break the exact-match check.
          got=$(flatpak run io.github.jeduden.mdsmith version | tail -n1)
          want="mdsmith ${VERSION}"
          if [ "$got" != "$want" ]; then
            echo "flatpak bundle version mismatch: got '$got', want '$want'" >&2
            exit 1
          fi
          echo "flatpak bundle: $got"
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: mdsmith-flatpak-bundle
          path: mdsmith-x86_64.flatpak

  smoke-test:
    # Wait until every channel is on the new version before checking
    # — the npm and PyPI registries can take ~60s to surface a fresh
    # publish, so the channel-specific install commands re-run if the
    # registry briefly returns the previous version.
    needs: [npm, pypi, release]
    strategy:
      fail-fast: false
      matrix:
        include:
          - channel: npm
            # node:lts (debian-slim) ships bash, so the install step
            # runs under the action's default `bash -e` shell. Alpine
            # would force `shell: sh` everywhere because busybox has
            # no bash before `apk add` runs.
            container: node:lts
            install: |
              # npm registry propagation can lag the publish by ~60s,
              # so retry with backoff until the just-published version
              # is resolvable. Mirrors the pip retry loop below.
              ok=0
              for attempt in 1 2 3 4 5; do
                if npm install -g --force "@mdsmith/cli@${VERSION#v}"; then
                  ok=1; break
                fi
                sleep 15
              done
              if [ "$ok" -ne 1 ]; then
                echo "npm install never succeeded after 5 attempts" >&2
                exit 1
              fi
            run: mdsmith version
          - channel: pip
            container: python:3.12-slim
            install: |
              python -m pip install --upgrade pip
              # `--upgrade` forces pip to pick the just-published
              # wheel rather than a cached older one.
              ok=0
              for attempt in 1 2 3 4 5; do
                if python -m pip install --upgrade "mdsmith==${VERSION#v}"; then
                  ok=1; break
                fi
                sleep 15
              done
              if [ "$ok" -ne 1 ]; then
                echo "pip install never succeeded after 5 attempts" >&2
                exit 1
              fi
            run: mdsmith version
          - channel: mise
            container: jdxcode/mise:latest
            # `ubi:jeduden/mdsmith@VER` resolves the binary directly
            # off the GitHub release the same `release` job above
            # just published. The shorter `mdsmith@VER` form depends
            # on the mise-plugins/registry follow-up; until that PR
            # lands the smoke-test would fail on every release, so
            # exercise the form that works today.
            install: |
              ok=0
              for attempt in 1 2 3 4 5; do
                if mise use -g "ubi:jeduden/mdsmith@${VERSION#v}"; then
                  ok=1; break
                fi
                sleep 15
              done
              if [ "$ok" -ne 1 ]; then
                echo "mise install never succeeded after 5 attempts" >&2
                exit 1
              fi
            run: |
              eval "$(mise activate bash --shims)"
              mdsmith version
    runs-on: ubuntu-latest
    container: ${{ matrix.container }}
    steps:
      - name: Install
        run: ${{ matrix.install }}
      - name: Verify version
        run: |
          got=$(${{ matrix.run }})
          want="mdsmith ${VERSION}"
          if [ "$got" != "$want" ]; then
            echo "channel=${{ matrix.channel }}: got '$got', want '$want'" >&2
            exit 1
          fi
          echo "channel=${{ matrix.channel }}: $got"

  # Nudge the Homebrew tap to bump its formula to this version right
  # away. Best-effort glue, not part of the gated publish: the tap at
  # jeduden/homebrew-mdsmith also self-bumps on a daily schedule, so a
  # missing token or a failed dispatch never blocks a release. The
  # token is a fine-grained PAT with Contents: write on the tap repo,
  # stored as the HOMEBREW_TAP_DISPATCH_TOKEN repo secret.
  notify-homebrew-tap:
    needs: [release]
    if: *release_repo_trigger_ok
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch a formula bump to the tap
        env:
          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_DISPATCH_TOKEN }}
          VERSION: ${{ env.VERSION }}
        run: |
          if [ -z "${GH_TOKEN:-}" ]; then
            echo "HOMEBREW_TAP_DISPATCH_TOKEN unset; the tap will self-bump on its daily schedule."
            exit 0
          fi
          gh api repos/jeduden/homebrew-mdsmith/dispatches \
            -f event_type=mdsmith-release \
            -f "client_payload[version]=${VERSION#v}"

  # A tool release also ships the website. The deploy itself lives
  # in pages.yml (its own workflow, also triggered by docs-only
  # pushes to main and by manual workflow_dispatch); this job just
  # calls it with the release version so the published site shows
  # the new version. Gated on `release` so the site is deployed
  # only after the release has been frozen — the draft is published
  # and immutable — so mdsmith.dev never advertises a version whose
  # GitHub release does not yet exist. `release` transitively
  # depends on `npm` (release -> vscode -> npm), so a failed npm
  # publish also blocks this deploy. That is intentional: with no
  # frozen release there is no version to ship the site for. `pypi`
  # is not in the release chain, so a PyPI outage does not block it.
  pages:
    needs: [release]
    if: *release_repo_trigger_ok
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: ./.github/workflows/pages.yml
    with:
      version: ${{ inputs.version }}