sdk-release.yml

name: SDK Release

# Release-please-driven publishing for @momentiq/dark-factory-cli and
# @momentiq/dark-factory-schemas. Pattern modeled on momentiq-ai/cerebe-
# platform/.github/workflows/sdk-release.yml.
#
# Replaces the manual `npm publish` dance (used for all alpha.4 -> alpha.9
# publishes), which has the failure modes we've already seen:
#   1. Local package.json bumps get reverted post-publish, so the source
#      drifts from the registry (local says alpha.7 while registry latest
#      is alpha.9). No git tag, no audit trail.
#   2. The 0.x `--tag alpha`-only gate (removed in #162) treated 0.x
#      releases as if they were pre-releases and never advanced `latest`,
#      so unpinned installs (`npx @momentiq/sage-cli`, bare `npm install`)
#      resolved a stale `latest`. The operative distinction is NOT
#      stability — `0.y.z` is SemVer "initial development" (the API may
#      change) — but whether the version is a PRERELEASE: `0.2.2` has no
#      `-` suffix, so npm assigns it `latest` by default; only a real
#      pre-release (e.g. `1.0.0-rc.1`) is withheld from `latest`.
#
# The flow this PR establishes:
#   conventional commits -> release-please opens "Release PR" with
#   version bumps + CHANGELOG -> human merges -> tag pushed -> this
#   workflow publishes to npm: non-prerelease versions -> `latest` (npm's
#   default), semver prereleases (a `-` suffix, e.g. 1.0.0-rc.1) -> `next`.
#
# Prerequisites (one-time):
#   - Repository secret `MOMENTIQ_NPM_PUBLISH_TOKEN`: an automation token for
#     `@momentiq` scope with publish permission (npmjs.com -> Access
#     tokens -> Generate New Token -> Automation -> scoped to @momentiq).
#   - Repository secrets `CI_BOT_APP_ID` + `CI_BOT_PRIVATE_KEY`: the
#     `momentiq-ci-bot` GitHub App credentials. Used to mint an
#     installation token that release-please-action runs under, so
#     release PRs are authored by the App (not `github-actions[bot]`).
#     This is load-bearing: PRs created with the default `GITHUB_TOKEN`
#     do NOT trigger downstream `pull_request` workflows (GitHub's
#     "prevent recursive workflows" rule), which would leave release
#     PRs blocked by required checks that never run. App-minted tokens
#     are exempt from that rule. The App requires `contents:write` +
#     `pull-requests:write` on this repo. See
#     https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs
#     and PR #103 (which was admin-merged because zero required workflows
#     ran on its head SHA) for the original incident.
#
# Until the secret is set, the `release-please` job still runs and opens
# Release PRs successfully -- only the publish jobs will fail-fast on
# missing token, which is the desired safety property.
#
# Security note: all `${{ ... }}` interpolations used in `run:` blocks are
# routed through `env:` declarations and dereferenced as `$VAR` to prevent
# shell-injection. See:
# https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write   # reserved for future npm provenance via OIDC

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      cli_released:       ${{ steps.release.outputs['packages/cli--release_created'] }}
      cli_version:        ${{ steps.release.outputs['packages/cli--version'] }}
      schemas_released:   ${{ steps.release.outputs['packages/schemas--release_created'] }}
      schemas_version:    ${{ steps.release.outputs['packages/schemas--version'] }}
      sage_cli_released:  ${{ steps.release.outputs['packages/sage-cli--release_created'] }}
      sage_cli_version:   ${{ steps.release.outputs['packages/sage-cli--version'] }}
    steps:
      # Mint an installation token for the `momentiq-ci-bot` GitHub App so
      # release-please-action runs under the App's identity. PRs created
      # or synchronized with the default `GITHUB_TOKEN` do NOT trigger
      # downstream `pull_request` workflows -- App-minted installation
      # tokens are exempt from that rule, so the required-status-check
      # contexts (agent-critic / pr-status-check / schema-check /
      # cycle-doc-validation / branch-protection-audit) actually run on
      # the release PR's head SHA. Without this, every release PR has to
      # be admin-merged (PR #103 evidence: zero required checks ran,
      # only the hosted W3 critic posted).
      # Skip cleanly if App credentials aren't configured yet (graceful
      # degrade). Until PJ adds CI_BOT_APP_ID + CI_BOT_PRIVATE_KEY repo
      # secrets, releases continue to work under GITHUB_TOKEN exactly as
      # before -- only the "downstream workflows run on release PR head
      # SHA" benefit is unrealized, requiring admin-merge for release
      # PRs. Once the App is configured, this step succeeds and the
      # App token flows into release-please below.
      - name: Detect App credentials
        id: detect-app
        env:
          # Both must be set; a partial config (one secret present, the
          # other missing) would still fail at create-github-app-token's
          # input validation, never reaching the fallback path.
          APP_CREDS_SET: ${{ secrets.CI_BOT_APP_ID != '' && secrets.CI_BOT_PRIVATE_KEY != '' }}
        run: |
          if [ "$APP_CREDS_SET" = "true" ]; then
            echo "has_app=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_app=false" >> "$GITHUB_OUTPUT"
            echo "::notice::CI_BOT_APP_ID and/or CI_BOT_PRIVATE_KEY not configured; release-please will run under GITHUB_TOKEN. Release PRs will require admin-merge (see PR #120) until both App credentials are added."
          fi

      - name: Mint CI bot installation token
        id: app-token
        if: steps.detect-app.outputs.has_app == 'true'
        # continue-on-error covers the "secrets present but App not
        # installed on this repo" case (HTTP 404 from
        # /repos/{owner}/{repo}/installation). Without this, that state
        # fails the entire release-please job. With it, the step's
        # outputs.token is empty and the `||` fallback below provides
        # GITHUB_TOKEN -- same behavior as if creds were absent. See
        # issue #123 for the failure mode this guards against.
        continue-on-error: true
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.CI_BOT_APP_ID }}
          private-key: ${{ secrets.CI_BOT_PRIVATE_KEY }}

      - name: Warn if App-token step degraded
        if: steps.app-token.outcome == 'failure'
        run: |
          echo "::warning::App credentials present but actions/create-github-app-token failed (likely App not installed on this repo). Falling back to GITHUB_TOKEN; release PRs will require admin-merge until installation is fixed. See issue #123."

      - uses: googleapis/release-please-action@v4
        id: release
        with:
          # Use App token if minted; otherwise fall back to GITHUB_TOKEN
          # (which still works, just doesn't trigger downstream workflows
          # on the release PR -- see PR #120 for full context).
          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

  publish-cli:
    name: Publish @momentiq/dark-factory-cli
    needs: release-please
    if: needs.release-please.outputs.cli_released == 'true'
    runs-on: ubuntu-latest
    steps:
      # Fail fast (before doing checkout/install/build work) if the npm
      # token isn't configured -- otherwise the job runs for ~30s and
      # then dies at `npm publish` with an opaque auth error.
      - name: Preflight (MOMENTIQ_NPM_PUBLISH_TOKEN must be set)
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
        run: |
          set -euo pipefail
          if [[ -z "${NODE_AUTH_TOKEN:-}" ]]; then
            echo "::error::MOMENTIQ_NPM_PUBLISH_TOKEN repo secret is unset. Generate an @momentiq automation token at npmjs.com and set it via: gh secret set MOMENTIQ_NPM_PUBLISH_TOKEN --repo momentiq-ai/dark-factory"
            exit 1
          fi

      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "20"
          registry-url: "https://registry.npmjs.org"
          cache: "npm"

      - name: Install (workspace)
        run: npm ci

      - name: Build (schemas first, then CLI -- targeted to avoid sage-cli's GH_TOKEN-dependent prebuild)
        run: |
          set -euo pipefail
          npm run build --workspace=@momentiq/dark-factory-schemas
          npm run build --workspace=@momentiq/dark-factory-cli

      - name: Validate CLI package (ESM smoke test + entrypoint resolves)
        working-directory: packages/cli
        run: |
          set -euo pipefail
          # ESM import smoke -- module-init side effects must not throw.
          node --input-type=module -e "import * as cli from './dist/index.js'; console.log('ESM import ok, exports:', Object.keys(cli).length, 'symbols')"
          # tsc doesn't set the +x bit; check file exists and the bin
          # entrypoint can be loaded as ESM. We don't run --help because
          # the CLI may try to read config / hit the network at startup.
          test -f dist/cli.js || (echo "::error::dist/cli.js missing" && exit 1)
          node --input-type=module -e "import('./dist/cli.js').catch(e => { console.error('bin import failed:', e.message); process.exit(1); })" \
            || (echo "::error::dist/cli.js failed to load as a module" && exit 1)

      - name: Publish to npm (stable -> latest, prerelease -> next)
        working-directory: packages/cli
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
          CLI_VERSION: ${{ needs.release-please.outputs.cli_version }}
        run: |
          set -euo pipefail
          # A stable release (no `-` prerelease suffix) publishes to `latest`
          # so unpinned installs resolve it; publishing 0.x `--tag alpha`-only
          # previously left `latest` stale (#162). A true prerelease (e.g.
          # 1.0.0-rc.1) goes to the `next` channel, off `latest`.
          if [[ "$CLI_VERSION" == *-* ]]; then
            npm publish --access public --tag next
          else
            npm publish --access public
          fi

  publish-schemas:
    name: Publish @momentiq/dark-factory-schemas
    needs: release-please
    if: needs.release-please.outputs.schemas_released == 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Preflight (MOMENTIQ_NPM_PUBLISH_TOKEN must be set)
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
        run: |
          set -euo pipefail
          if [[ -z "${NODE_AUTH_TOKEN:-}" ]]; then
            echo "::error::MOMENTIQ_NPM_PUBLISH_TOKEN repo secret is unset. Generate an @momentiq automation token at npmjs.com and set it via: gh secret set MOMENTIQ_NPM_PUBLISH_TOKEN --repo momentiq-ai/dark-factory"
            exit 1
          fi

      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "20"
          registry-url: "https://registry.npmjs.org"
          cache: "npm"

      - name: Install (workspace)
        run: npm ci

      - name: Build schemas
        run: npm run build --workspace=@momentiq/dark-factory-schemas

      - name: Publish to npm (stable -> latest, prerelease -> next)
        working-directory: packages/schemas
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
          SCHEMAS_VERSION: ${{ needs.release-please.outputs.schemas_version }}
        run: |
          set -euo pipefail
          # A stable release (no `-` prerelease suffix) publishes to `latest`
          # so unpinned installs resolve it; publishing 0.x `--tag alpha`-only
          # previously left `latest` stale (#162). A true prerelease (e.g.
          # 1.0.0-rc.1) goes to the `next` channel, off `latest`.
          if [[ "$SCHEMAS_VERSION" == *-* ]]; then
            npm publish --access public --tag next
          else
            npm publish --access public
          fi

  publish-sage-cli:
    name: Publish @momentiq/sage-cli
    needs: release-please
    if: needs.release-please.outputs.sage_cli_released == 'true'
    runs-on: ubuntu-latest
    steps:
      # sage-cli needs TWO repo secrets:
      #   1. MOMENTIQ_NPM_PUBLISH_TOKEN -- the @momentiq automation token
      #      (same one publish-cli + publish-schemas use)
      #   2. SAGE_BLUEPRINT_READ_TOKEN -- fine-grained PAT with
      #      `Contents: Read` on momentiq-ai/sage-blueprint, used at
      #      build time by scripts/bundle-template.mjs to fetch the
      #      sage-blueprint template into packages/sage-cli/template/
      #      before tsc builds. The bundled template ships in the npm
      #      tarball via `files: ["dist", "template", ...]`.
      - name: Preflight (MOMENTIQ_NPM_PUBLISH_TOKEN must be set)
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
        run: |
          set -euo pipefail
          if [[ -z "${NODE_AUTH_TOKEN:-}" ]]; then
            echo "::error::MOMENTIQ_NPM_PUBLISH_TOKEN repo secret is unset. Generate an @momentiq automation token at npmjs.com and set it via: gh secret set MOMENTIQ_NPM_PUBLISH_TOKEN --repo momentiq-ai/dark-factory"
            exit 1
          fi

      - name: Preflight (SAGE_BLUEPRINT_READ_TOKEN must be set)
        env:
          GH_TOKEN_PROBE: ${{ secrets.SAGE_BLUEPRINT_READ_TOKEN }}
        run: |
          set -euo pipefail
          if [[ -z "${GH_TOKEN_PROBE:-}" ]]; then
            echo "::error::SAGE_BLUEPRINT_READ_TOKEN repo secret is unset. Generate a fine-grained PAT with Contents:Read on momentiq-ai/sage-blueprint and set it via: gh secret set SAGE_BLUEPRINT_READ_TOKEN --repo momentiq-ai/dark-factory"
            exit 1
          fi

      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "20"
          registry-url: "https://registry.npmjs.org"
          cache: "npm"

      - name: Install (workspace)
        run: npm ci

      - name: Build sage-cli (prebuild bundles sage-blueprint template -- needs GH_TOKEN)
        env:
          GH_TOKEN: ${{ secrets.SAGE_BLUEPRINT_READ_TOKEN }}
          # SAGE_BLUEPRINT_REF defaults to 'main'; override to pin a
          # specific tag per release. Comment out to always track main.
          # SAGE_BLUEPRINT_REF: "v1.2.3"
        run: npm run build --workspace=@momentiq/sage-cli

      - name: Validate sage-cli package (ESM smoke + bin runs + bundle complete)
        working-directory: packages/sage-cli
        run: |
          set -euo pipefail
          # ESM library import smoke -- module-init side effects must not throw.
          node --input-type=module -e "import * as cli from './dist/index.js'; console.log('ESM import ok, exports:', Object.keys(cli).length, 'symbols')"
          # Bin entry exists.
          test -f dist/cli.js || (echo "::error::dist/cli.js missing" && exit 1)
          # Bin runs cleanly as a CLI (this is what `npx @momentiq/sage-cli ...`
          # actually does). --version exits 0 and prints the banner; this
          # exercises the version-banner read of template/.bundle-info.json
          # too, so a missing bundle would also fail here.
          # Note: do NOT smoke-test by `import('./dist/cli.js')` -- the bin
          # parses argv at load time, sees no command, and commander exits
          # 1 by design. That is correct behavior for a bin and is gated
          # behind an is-main-module check in src/cli.ts.
          VERSION_OUTPUT=$(node ./dist/cli.js --version)
          echo "$VERSION_OUTPUT"
          echo "$VERSION_OUTPUT" | grep -q '@momentiq/sage-cli' || (echo "::error::sage --version output missing package name" && exit 1)
          echo "$VERSION_OUTPUT" | grep -qE 'bundled (momentiq-ai/)?sage-blueprint@' || (echo "::error::sage --version output missing bundled sage-blueprint commit" && exit 1)
          # Bundled template is complete.
          test -f template/copier.yaml || (echo "::error::bundled template missing copier.yaml" && exit 1)
          test -d template/template     || (echo "::error::bundled template missing template/ dir" && exit 1)
          test -f template/.bundle-info.json || (echo "::error::bundled template missing .bundle-info.json" && exit 1)
          echo "bundle info:"; cat template/.bundle-info.json

      - name: Publish to npm (stable -> latest, prerelease -> next)
        working-directory: packages/sage-cli
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOMENTIQ_NPM_PUBLISH_TOKEN }}
          SAGE_CLI_VERSION: ${{ needs.release-please.outputs.sage_cli_version }}
        run: |
          set -euo pipefail
          # A stable release (no `-` prerelease suffix) publishes to `latest`
          # so unpinned installs resolve it; publishing 0.x `--tag alpha`-only
          # previously left `latest` stale (#162). A true prerelease (e.g.
          # 1.0.0-rc.1) goes to the `next` channel, off `latest`.
          if [[ "$SAGE_CLI_VERSION" == *-* ]]; then
            npm publish --access public --tag next
          else
            npm publish --access public
          fi

  # On-publish auto-bump fan-out (#280). After @momentiq/dark-factory-cli is
  # published, POST a repository_dispatch{df-cli-released, version} to every
  # consumer in .github/consumers.json. Each consumer's thin df-cli-bump.yml
  # receiver (`uses:` .github/workflows/consumer-cli-bump.yml) then opens a
  # co-bump PR. This is the publish-triggered path PJ chose over Renovate
  # polling: vanilla Renovate cannot fire on a publish event, and for a
  # first-party package whose release cadence we control, dispatch is strictly
  # tighter (PR opens within minutes of publish, no Mend dependency).
  dispatch-consumers:
    name: Dispatch on-publish bump to consumers
    needs: [release-please, publish-cli]
    if: needs.release-please.outputs.cli_released == 'true'
    runs-on: ubuntu-latest
    steps:
      # Reuse the momentiq-ci-bot App identity (same secrets release-please
      # uses) to POST cross-repo dispatches. The App must be installed on each
      # consumer in .github/consumers.json with `contents: write` (the
      # permission the dispatches endpoint requires). Until it is, this job
      # graceful-degrades — logs a notice and exits 0 — so a successful publish
      # is NEVER blocked by missing cross-repo dispatch auth.
      - name: Detect dispatch App credentials
        id: detect-app
        env:
          APP_CREDS_SET: ${{ secrets.CI_BOT_APP_ID != '' && secrets.CI_BOT_PRIVATE_KEY != '' }}
        run: |
          set -euo pipefail
          if [ "$APP_CREDS_SET" = "true" ]; then
            echo "has_app=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_app=false" >> "$GITHUB_OUTPUT"
            echo "::notice::CI_BOT_APP_ID/CI_BOT_PRIVATE_KEY not set; skipping consumer dispatch. Consumers must be bumped manually until the App is configured (see .github/consumers.json)."
          fi

      - name: Mint dispatch token (org-scoped)
        id: app-token
        if: steps.detect-app.outputs.has_app == 'true'
        # continue-on-error covers "creds present but App not installed on the
        # consumer repos" — token mint 404s; we degrade to skip rather than
        # failing the release after a successful publish.
        continue-on-error: true
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.CI_BOT_APP_ID }}
          private-key: ${{ secrets.CI_BOT_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}

      - name: Warn if token mint degraded
        if: steps.detect-app.outputs.has_app == 'true' && steps.app-token.outcome == 'failure'
        run: echo "::warning::App creds present but token mint failed (App likely not installed across consumer repos). Skipping dispatch; consumers need manual bump."

      - uses: actions/checkout@v6
        if: steps.app-token.outputs.token != ''

      - name: Dispatch df-cli-released to each consumer
        if: steps.app-token.outputs.token != ''
        env:
          # Trusted inputs only: the committed consumers.json and the
          # release-please-emitted version. Nothing here is attacker-controlled.
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          CLI_VERSION: ${{ needs.release-please.outputs.cli_version }}
        run: |
          set -euo pipefail
          mapfile -t REPOS < <(jq -r '.consumers[].repo' .github/consumers.json)
          echo "Dispatching df-cli-released (version=$CLI_VERSION) to ${#REPOS[@]} consumer(s)."
          fail=0
          for repo in "${REPOS[@]}"; do
            if gh api -X POST "repos/${repo}/dispatches" \
                 -f "event_type=df-cli-released" \
                 -f "client_payload[version]=${CLI_VERSION}" 2>/tmp/dispatch_err; then
              echo "  ok   ${repo}"
            else
              echo "  fail ${repo}: $(cat /tmp/dispatch_err)"
              echo "::warning::repository_dispatch to ${repo} failed (App not installed there, or no df-cli-bump.yml receiver yet). Bump it manually."
              fail=$((fail + 1))
            fi
          done
          # A consumer that can't receive must NOT fail the release — the
          # publish already succeeded. Report the count and exit 0.
          echo "Dispatch complete: $(( ${#REPOS[@]} - fail ))/${#REPOS[@]} succeeded."