@norskvideo/ctl-dev-kit 0.2.25 → 0.2.27

package/conventions/bot-prs.yml

@@ -0,0 +1,167 @@
+# Land the pin bots' green PRs; put the red ones on the product dashboard.
+#
+# Three bots keep a product fresh: upgrade-latest (the Norsk nightly line),
+# sync-dev-kit (this package) and sync-ctl-packages (the ctl-* / moq-* npm
+# family). The first two land on main when their gate is green and open a PR
+# when it is not; sync-ctl-packages ALWAYS opens a PR, because its gate cannot
+# run the smoke tier its packages drive. Nothing then acted on those PRs: green
+# ones sat unmerged (studio's ctl-sdk was twenty releases behind on 2026-10-03,
+# its PR open since 09-03) and red ones were invisible, because the bot that
+# opened them reports success. With a product count that only goes up, "someone
+# will notice" is not a process.
+#
+# So, for every open PR whose branch a bot owns:
+#   - every check on its head has passed and it merges cleanly -> squash-merge it
+#     (the PR's checks + smoke ARE the verdict; integration then runs on main);
+#   - a check failed, it conflicts with main, or it is a draft (the bot's own
+#     gate was red) -> list it, and report this repo's `bot-prs` cell RED on the
+#     product dashboard, which is the Discord message people actually read;
+#   - checks still running -> leave it for the next trigger.
+# The cell goes green again once nothing is red.
+#
+# Runs when a PR's checks or smoke finish (the prompt path), hourly as a sweep,
+# and on demand. No checkout: it only talks to the GitHub API, so it needs none
+# of the runner-workspace steps the building workflows carry.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/bot-prs.yml) and copied
+# verbatim into each product repo -- it reads its dashboard key from this repo's
+# upgrade-latest.yml rather than carrying one -- so sync-drift creates it where
+# absent and check:drift fails a copy that diverges. Never hand-edit the copy.
+name: bot-prs
+
+on:
+  workflow_run:
+    workflows: [checks, smoke]
+    types: [completed]
+  schedule:
+    - cron: "23 * * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  checks: read
+  pull-requests: read
+
+concurrency:
+  # One at a time per repo, and never cancelled: a merge half-done by a run that
+  # was cancelled is worse than a second run finding nothing left to do.
+  group: bot-prs-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  triage:
+    runs-on: x64
+    steps:
+      - name: Merge green bot PRs, report red ones
+        id: triage
+        env:
+          # Reads go through the job's own token, which the permissions above
+          # scope to exactly what is read; CI_DISPATCH_TOKEN (a PAT) has no
+          # Checks access, and the check-runs call returned an error object.
+          # Merges and branch deletes go through the PAT, because a push made
+          # with GITHUB_TOKEN does not trigger main's own workflows.
+          READ_TOKEN: ${{ github.token }}
+          WRITE_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          api="https://api.github.com/repos/$REPO"
+          curl_as() { local tok="$1"; shift; curl -sS --retry 3 --retry-all-errors -H "Authorization: Bearer $tok" -H "Accept: application/vnd.github+json" "$@"; }
+          gh_api() { curl_as "$READ_TOKEN" "$@"; }
+          gh_write() { curl_as "$WRITE_TOKEN" "$@"; }
+          # An API error is a JSON object with a message; say what it was rather
+          # than letting jq fail later on a missing field.
+          expect() {
+            local what="$1" filter="$2" body="$3"
+            jq -e "$filter" >/dev/null 2>&1 <<<"$body" && return 0
+            echo "::error::$what: $(jq -r '.message // .' <<<"$body" 2>/dev/null || echo "$body")"
+            exit 1
+          }
+
+          # The bots own exactly these branches (see each workflow's PR step).
+          pulls="$(gh_api "$api/pulls?state=open&per_page=100")"
+          expect "listing open PRs" 'type == "array"' "$pulls"
+          prs="$(jq -c --arg repo "$REPO" '
+            [.[] | select(.head.repo.full_name == $repo)
+                 | select(.head.ref | test("^(upgrade-latest/|sync-dev-kit/|chore/sync-ctl-packages$)"))
+                 | {number, ref: .head.ref, sha: .head.sha, draft, url: .html_url}]' <<<"$pulls")"
+
+          red=()
+          merged=()
+          while IFS= read -r pr; do
+            [ -n "$pr" ] || continue
+            n="$(jq -r .number <<<"$pr")"; ref="$(jq -r .ref <<<"$pr")"; sha="$(jq -r .sha <<<"$pr")"
+            runs="$(gh_api "$api/commits/$sha/check-runs?per_page=100")"
+            expect "reading checks for #$n" '.check_runs | type == "array"' "$runs"
+            failed="$(jq -r '[.check_runs[] | select(.conclusion | IN("failure","cancelled","timed_out","action_required","startup_failure")) | .name] | unique | join(", ")' <<<"$runs")"
+            pending="$(jq -r '[.check_runs[] | select(.status != "completed")] | length' <<<"$runs")"
+            passed="$(jq -r '[.check_runs[] | select(.conclusion == "success")] | length' <<<"$runs")"
+            if [ -n "$failed" ]; then red+=("#$n $ref: failing $failed"); continue; fi
+            if [ "$(jq -r .draft <<<"$pr")" = "true" ]; then red+=("#$n $ref: draft (its bot's gate was red)"); continue; fi
+            if [ "$pending" -gt 0 ] || [ "$passed" -eq 0 ]; then echo "#$n $ref: checks not finished; next time"; continue; fi
+            # GitHub computes mergeability lazily; ask until it has an answer.
+            mergeable=null
+            for _ in 1 2 3 4 5; do
+              mergeable="$(gh_api "$api/pulls/$n" | jq -r .mergeable)"
+              [ "$mergeable" != "null" ] && break
+              sleep 3
+            done
+            if [ "$mergeable" != "true" ]; then red+=("#$n $ref: does not merge cleanly with main"); continue; fi
+            # sha pins the merge to what was checked: a bot force-pushing the
+            # branch meanwhile makes this refuse rather than land unchecked code.
+            res="$(gh_write -X PUT "$api/pulls/$n/merge" -d "$(jq -nc --arg sha "$sha" '{merge_method:"squash", sha:$sha}')")"
+            if [ "$(jq -r '.merged // false' <<<"$res")" = "true" ]; then
+              merged+=("#$n")
+              echo "merged #$n ($ref)"
+              # The bots recreate their branch on the next bump.
+              gh_write -X DELETE "$api/git/refs/heads/$ref" -o /dev/null || true
+            else
+              red+=("#$n $ref: merge refused: $(jq -r '.message // "unknown"' <<<"$res")")
+            fi
+          done < <(jq -c '.[]' <<<"$prs")
+
+          if [ "${#red[@]}" -gt 0 ]; then
+            state=failure
+            detail="$(printf '%s; ' "${red[@]}")"
+            for r in "${red[@]}"; do echo "::warning::bot PR needs a human: $r"; done
+          else
+            state=success
+            detail="${merged[*]:+merged ${merged[*]}}"
+          fi
+          echo "state=$state" >> "$GITHUB_OUTPUT"
+          echo "detail=${detail%; }" >> "$GITHUB_OUTPUT"
+
+      - name: Report to the product dashboard
+        # Always: a triage that broke is exactly what nobody would otherwise see.
+        if: always()
+        env:
+          TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+          READ_TOKEN: ${{ github.token }}
+          STATUS: ${{ steps.triage.outputs.state || 'failure' }}
+          DETAIL: ${{ steps.triage.outputs.detail || 'the bot-PR triage itself failed; see the run' }}
+          SHA: ${{ github.sha }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # The dashboard key is the one upgrade-latest.yml reports under, read
+          # from it so this file can stay byte-identical across products.
+          product="$(curl -sS -H "Authorization: Bearer $READ_TOKEN" -H "Accept: application/vnd.github.raw" \
+            "https://api.github.com/repos/$REPO/contents/.github/workflows/upgrade-latest.yml" \
+            | sed -nE 's/^[[:space:]]*product:[[:space:]]*([^[:space:]]+).*/\1/p' | head -1)"
+          if [ -z "$product" ] || [ "$product" = "__PRODUCT__" ]; then
+            echo "::warning::no product key in upgrade-latest.yml; not reporting to the dashboard"
+            exit 0
+          fi
+          ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          payload="$(jq -cn \
+            --arg product "$product" --arg pipeline bot-prs --arg conclusion "$STATUS" \
+            --arg sha "$SHA" --arg runUrl "$RUN_URL" --arg ts "$ts" --arg detail "$DETAIL" \
+            '{event_type: "ci-status", client_payload: (
+               {product: $product, pipeline: $pipeline, conclusion: $conclusion, sha: $sha, runUrl: $runUrl, ts: $ts}
+               + (if $detail == "" then {} else {detail: $detail} end)
+             )}')"
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.github+json" \
+            https://api.github.com/repos/id3as/ci-workflows/dispatches -d "$payload")"
+          [ "$code" = "204" ] || echo "::warning::dashboard dispatch returned HTTP $code"

package/conventions/check-drift.ts

@@ -256,6 +256,10 @@ export interface CanonicalBytes {
   /** conventions/sync-ctl-packages.yml — the ctl-* pin freshness PR. No per-repo
    *  line at all, so it is verbatim and sync-drift creates it where absent. */
   syncCtlPackages: string;
+  /** conventions/bot-prs.yml -- merges the pin bots' green PRs and reports red
+   *  ones. Verbatim (it reads its dashboard key at run time), so sync-drift
+   *  creates it where absent, like sync-ctl-packages. */
+  botPrs: string;
   publishDocs: string;
   /** conventions/build-docs.yml — the embedded docs variant (bundle -> image, no upload). */
   buildDocs: string;
@@ -683,6 +687,13 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     push(`.github/workflows/sync-ctl-packages.yml differs from conventions/sync-ctl-packages.yml. ${RESYNC}`);
   }
 
+  // bot-prs.yml: the same shape -- optional until a repo's first sync creates
+  // it, verbatim once present.
+  const botPrsPath = join(repoRoot, ".github", "workflows", "bot-prs.yml");
+  if (existsSync(botPrsPath) && readFileSync(botPrsPath, "utf8") !== canonical.botPrs) {
+    push(`.github/workflows/bot-prs.yml differs from conventions/bot-prs.yml. ${RESYNC}`);
+  }
+
   // smoke.yml is OPTIONAL until every product carries a tests/smoke.spec.ts
   // (04b s7.2 sequences the required-file rule last). When present it is the
   // shared, single-sourced workflow; only its `product:` dispatch key and the
@@ -793,6 +804,7 @@ if (import.meta.main) {
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
     syncCtlPackages: readFileSync(join(import.meta.dir, "sync-ctl-packages.yml"), "utf8"),
+    botPrs: readFileSync(join(import.meta.dir, "bot-prs.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
     withDisplay: readFileSync(join(import.meta.dir, "..", "doc-guide", "with-display.sh"), "utf8"),

package/conventions/sync-dev-kit.yml

@@ -167,8 +167,25 @@ jobs:
 
       - name: Land the freshness bump on main (gate green)
         if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'success'
+        env:
+          API_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
         run: |
           set -euo pipefail
+          # This bump is about to land, which makes any sync-dev-kit/* PR an earlier
+          # red run opened obsolete. Left open they piled up -- nine were closed
+          # by hand on 2026-10-03 -- so close them once the push has landed.
+          # Best-effort: a failure here must not fail the landing.
+          close_superseded() {
+            api="https://api.github.com/repos/$GITHUB_REPOSITORY"
+            auth=(-H "Authorization: Bearer $API_TOKEN" -H "Accept: application/vnd.github+json")
+            for n in $(curl -sS "${auth[@]}" "$api/pulls?state=open&per_page=100" \
+                | jq -r --arg repo "$GITHUB_REPOSITORY" '.[] | select(.head.repo.full_name == $repo and (.head.ref | startswith("sync-dev-kit/"))) | .number'); do
+              curl -sS -o /dev/null "${auth[@]}" -X POST "$api/issues/$n/comments" \
+                -d '{"body":"Superseded: a later sync-dev-kit run landed its bump on main."}'
+              curl -sS -o /dev/null "${auth[@]}" -X PATCH "$api/pulls/$n" -d '{"state":"closed"}'
+              echo "closed superseded PR #$n"
+            done
+          }
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add -A
@@ -184,7 +201,7 @@ jobs:
           # is schedule/dispatch-only, so no loop). Rebase-and-retry so a commit
           # landing mid-run does not red the sync; a real conflict aborts.
           for attempt in 1 2 3 4 5; do
-            if git push origin HEAD:main; then exit 0; fi
+            if git push origin HEAD:main; then close_superseded || true; exit 0; fi
             echo "push rejected (attempt $attempt) - rebasing onto latest origin/main"
             # --unshallow, not a plain fetch: these runners keep their .git
             # between jobs, and a commit an earlier job fetched at depth 1 stays

package/conventions/sync-drift.ts

@@ -307,6 +307,13 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: Pr
     ".github/workflows/sync-ctl-packages.yml",
     r.written,
   );
+  // bot-prs.yml likewise: verbatim, and created where absent.
+  writeIfChanged(
+    join(repoRoot, ".github/workflows/bot-prs.yml"),
+    canonical.botPrs,
+    ".github/workflows/bot-prs.yml",
+    r.written,
+  );
   // build-image.yml is the Studio bundle-image workflow; an sdk-app ships its
   // own container, so it is not synced for that shape.
   if (shape === "studio") syncBuildImage(repoRoot, canonical.buildImage, r);
@@ -346,6 +353,7 @@ if (import.meta.main) {
     upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
     syncCtlPackages: readFileSync(join(dir, "sync-ctl-packages.yml"), "utf8"),
+    botPrs: readFileSync(join(dir, "bot-prs.yml"), "utf8"),
     publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(dir, "build-docs.yml"), "utf8"),
     withDisplay: readFileSync(join(dir, "..", "doc-guide", "with-display.sh"), "utf8"),

package/conventions/upgrade-latest.yml

@@ -297,8 +297,25 @@ jobs:
 
       - name: Land the bump on main (gate green)
         if: steps.bump.outputs.changed == '1' && steps.gate.outcome == 'success'
+        env:
+          API_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
         run: |
           set -euo pipefail
+          # This bump is about to land, which makes any upgrade-latest/* PR an earlier
+          # red run opened obsolete. Left open they piled up -- nine were closed
+          # by hand on 2026-10-03 -- so close them once the push has landed.
+          # Best-effort: a failure here must not fail the landing.
+          close_superseded() {
+            api="https://api.github.com/repos/$GITHUB_REPOSITORY"
+            auth=(-H "Authorization: Bearer $API_TOKEN" -H "Accept: application/vnd.github+json")
+            for n in $(curl -sS "${auth[@]}" "$api/pulls?state=open&per_page=100" \
+                | jq -r --arg repo "$GITHUB_REPOSITORY" '.[] | select(.head.repo.full_name == $repo and (.head.ref | startswith("upgrade-latest/"))) | .number'); do
+              curl -sS -o /dev/null "${auth[@]}" -X POST "$api/issues/$n/comments" \
+                -d '{"body":"Superseded: a later upgrade-latest run landed its bump on main."}'
+              curl -sS -o /dev/null "${auth[@]}" -X PATCH "$api/pulls/$n" -d '{"state":"closed"}'
+              echo "closed superseded PR #$n"
+            done
+          }
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add -A
@@ -316,7 +333,7 @@ jobs:
           # landing mid-run does not fail the bump; a genuine content conflict
           # still aborts loudly rather than force-pushing over other work.
           for attempt in 1 2 3 4 5; do
-            if git push origin HEAD:main; then exit 0; fi
+            if git push origin HEAD:main; then close_superseded || true; exit 0; fi
             echo "push rejected (attempt $attempt) - rebasing onto latest origin/main"
             # --unshallow, not a plain fetch: these runners keep their .git
             # between jobs, and a commit an earlier job fetched at depth 1 stays

package/create-product/canon.ts

@@ -19,6 +19,7 @@ export interface Canon {
   upgradeLatest: string;
   syncDevKit: string;
   syncCtlPackages: string;
+  botPrs: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -44,6 +45,7 @@ export function loadCanon(): Canon {
     upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(conventionsDir, "sync-dev-kit.yml"), "utf8"),
     syncCtlPackages: readFileSync(join(conventionsDir, "sync-ctl-packages.yml"), "utf8"),
+    botPrs: readFileSync(join(conventionsDir, "bot-prs.yml"), "utf8"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
     buildDocs: readFileSync(join(conventionsDir, "build-docs.yml"), "utf8"),
     withDisplay: readFileSync(join(conventionsDir, "..", "doc-guide", "with-display.sh"), "utf8"),

package/create-product/create-product.ts

@@ -222,6 +222,7 @@ function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[]
     { path: ".github/workflows/upgrade-latest.yml", content: fillProduct(canon.upgradeLatest) },
     { path: ".github/workflows/sync-dev-kit.yml", content: fillProduct(canon.syncDevKit) },
     { path: ".github/workflows/sync-ctl-packages.yml", content: canon.syncCtlPackages },
+    { path: ".github/workflows/bot-prs.yml", content: canon.botPrs },
     { path: ".github/workflows/build-image.yml", content: fillProduct(canon.buildImage) },
     { path: ".github/actions/ci-status-dispatch/action.yml", content: loadAsset("ci-status-dispatch.yml") },
     { path: "manifest.seed.json", content: seedJson(ctx) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",