@norskvideo/ctl-dev-kit 0.1.9 → 0.1.11

package/conventions/CLAUDE.core.md

@@ -45,5 +45,21 @@
   named capability in its manifest's `requires: [...]`; ctl refuses only if it
   lacks that capability. Reach for a capability as rarely as possible — it is the
   escape hatch, not the default.
+- **The shared CI workflow is single-sourced too.** `.github/workflows/upgrade-latest.yml`
+  is copied verbatim from `@norskvideo/ctl-dev-kit` (`conventions/upgrade-latest.yml`),
+  same as this core block and `flake.nix`; `check:drift` fails CI if a copy
+  diverges. Only the `product:` key is per-repo. Never hand-edit the copy — edit
+  the dev-kit source and re-sync.
+- **A config-driven workflow needs a parity-checked invariant contract.** If this
+  product emits its Studio graph dynamically from config, every config dimension's
+  rules are documented as stable-ID statements in
+  `shared/src/schemas/INVARIANTS.md`, and every ID has an executable rule in the
+  composer rule-sweep (`shared/src/workflow/composer-rules.test.ts`). A parity
+  guard in that suite fails CI on any drift — a documented ID with no rule, or a
+  rule with no doc ID. So a config change is never done until the invariant is in
+  BOTH the doc and its test (same ID, added together); a runtime-only invariant
+  the emitted graph can't show goes in the explicit untestable-IDs set
+  (`COMPOSER_UNTESTABLE_IDS`), still parity-checked. `norsk-ctl-product-playout`
+  and `-commentary` are the worked examples.
 
 <!-- END ctl-shared-conventions v1 -->

package/conventions/check-drift.ts

@@ -36,6 +36,24 @@ function firstDiffLine(actual: string, expected: string): string {
   return "content differs";
 }
 
+// The one legitimately per-repo line in upgrade-latest.yml: the dashboard key
+// the nightly result is dispatched under. Everything else is verbatim-shared.
+const PRODUCT_LINE = /^(\s*product:\s*).*$/m;
+const PRODUCT_SENTINEL = "__PRODUCT__";
+
+function workflowProblem(actual: string, canonical: string): string | undefined {
+  // Compare structure with the product value masked so any real key passes, then
+  // separately reject a copy that still carries the unfilled sentinel.
+  const mask = (s: string) => s.replace(PRODUCT_LINE, `$1${PRODUCT_SENTINEL}`);
+  if (mask(actual) !== mask(canonical)) {
+    return `.github/workflows/upgrade-latest.yml has drifted from @norskvideo/ctl-dev-kit conventions/upgrade-latest.yml (${firstDiffLine(mask(actual), mask(canonical))}). ${RESYNC}`;
+  }
+  if (actual.match(/^\s*product:\s*(\S+)/m)?.[1] === PRODUCT_SENTINEL) {
+    return `.github/workflows/upgrade-latest.yml still has the ${PRODUCT_SENTINEL} placeholder — set \`product:\` to this repo's dashboard key.`;
+  }
+  return undefined;
+}
+
 function coreProblem(claude: string, canonicalCore: string): string | undefined {
   if (claude.includes(canonicalCore)) return undefined;
 
@@ -48,7 +66,10 @@ function coreProblem(claude: string, canonicalCore: string): string | undefined
   return `CLAUDE.md fenced core has drifted from @norskvideo/ctl-dev-kit conventions/CLAUDE.core.md (${firstDiffLine(region, canonicalCore.trimEnd())}). ${RESYNC}`;
 }
 
-export function checkDrift(repoRoot: string, canonical: { core: string; flake: string }): DriftReport {
+export function checkDrift(
+  repoRoot: string,
+  canonical: { core: string; flake: string; upgradeLatest: string },
+): DriftReport {
   const problems: string[] = [];
 
   const claudePath = join(repoRoot, "CLAUDE.md");
@@ -73,6 +94,15 @@ export function checkDrift(repoRoot: string, canonical: { core: string; flake: s
     }
   }
 
+  // upgrade-latest.yml is OPTIONAL — a product may ship without a nightly bump
+  // (e.g. until it has an integration tier). But when present it is the shared,
+  // single-sourced workflow and must not diverge.
+  const workflowPath = join(repoRoot, ".github", "workflows", "upgrade-latest.yml");
+  if (existsSync(workflowPath)) {
+    const problem = workflowProblem(readFileSync(workflowPath, "utf8"), canonical.upgradeLatest);
+    if (problem) problems.push(problem);
+  }
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -81,10 +111,11 @@ if (import.meta.main) {
   const canonical = {
     core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
+    upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical);
   if (report.ok) {
-    console.log("drift-check: CLAUDE.md core + flake.nix match @norskvideo/ctl-dev-kit.");
+    console.log("drift-check: CLAUDE.md core + flake.nix + upgrade-latest.yml match @norskvideo/ctl-dev-kit.");
     process.exit(0);
   }
   console.error(

package/conventions/upgrade-latest.yml

@@ -0,0 +1,203 @@
+# Keep the product fresh against the Norsk "nightly" channel (RFC 0001 —
+# product version freshness). The media + studio engine versions are pinned in
+# two coupled places that MUST move together: the npm `overrides` in the root
+# package.json (build-time libraries) and manifest.seed.json (the launched
+# container image tags). Both use the identical version string, so a bump is a
+# global string-replace of old->new across every tracked file — which also
+# updates the version-pin guard test in lockstep, no drift. Also rebumps the
+# dev flake's pinned norsk-ctl daemon to the `latest` channel (dev-only; CI
+# downloads ctl directly, so a stale pin never affects CI or customers).
+#
+# Commits the bump straight to main (nightly cron + on demand). Note: a
+# GITHUB_TOKEN push does not retrigger build-image/integration (Actions'
+# recursion guard), so the next human push validates the bump; a sad pony on
+# that run flags a bad nightly to revert. Runs nightly + on demand.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/upgrade-latest.yml) and
+# copied verbatim into each product repo; the check:drift gate fails CI if a copy
+# diverges. Only the `product:` value below is per-repo (set it to this repo's
+# dashboard key); everything else must match the dev-kit source. Never hand-edit
+# the copy — edit the dev-kit source and re-sync.
+name: upgrade-latest
+
+on:
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    runs-on: x64
+    outputs:
+      changed: ${{ steps.bump.outputs.changed }}
+      summary: ${{ steps.bump.outputs.summary }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Resolve the nightly channel and rewrite the coupled pins
+        id: bump
+        run: |
+          set -euo pipefail
+          reg="https://registry.npmjs.org"
+          changed=0
+
+          # Accumulate a COMPACT summary: only the components that actually moved
+          # get an entry, so a no-op nightly (old == new) posts nothing. Was: the
+          # full media + studio-lib + studio-image triple every night for every
+          # product, even when nothing changed — pure dashboard noise.
+          parts=()
+
+          # MEDIA: the npm packages and the launched image are built from the SAME
+          # commit (their hash suffixes match), so one version string drives the
+          # whole family. norsk-sdk is the family reference; read its nightly
+          # dist-tag off the registry (curl+jq — the runner has no npm) and rewrite
+          # every occurrence (overrides, sub-package deps, manifest image ref,
+          # version-pin test) EXCEPT the lockfile, which bun install regenerates.
+          old_media="$(jq -r '.latest.media | split(":")[1]' manifest.seed.json)"
+          new_media="$(curl -fsSL "$reg/@norskvideo%2Fnorsk-sdk" | jq -r '."dist-tags".nightly')"
+          [ -n "$new_media" ] && [ "$new_media" != "null" ] || { echo "could not resolve norsk-sdk nightly"; exit 1; }
+          echo "media: $old_media -> $new_media"
+          if [ "$old_media" != "$new_media" ]; then
+            git grep -lF "$old_media" -- . ':!bun.lock' | xargs -r sed -i "s|$old_media|$new_media|g"
+            changed=1
+            parts+=("media \`$new_media\`")
+          fi
+
+          # STUDIO: unlike media, Norsk builds the studio npm packages and the
+          # studio Docker image from DIFFERENT commits — their hash suffixes never
+          # match — so one version string can't serve both: pinning the launched
+          # image to the npm nightly yields a tag that was never pushed (integration
+          # then dies on "manifest unknown"). Resolve the two apart: build libraries
+          # from npm, the launched image from Docker Hub's newest published tag ON
+          # THE SAME version line (so it's pullable AND matches the libs'
+          # major.minor.patch). Rewrite the image ref FIRST, then the bare library
+          # version — so even when the two happen to coincide, the image ref is
+          # already moved and the bare-version rewrite only touches the npm overrides
+          # (no dependence on which files hold each — some products have no
+          # version-pin test).
+          old_studio_lib="$(jq -r '.overrides["@norskvideo/norsk-studio"]' package.json)"
+          new_studio_lib="$(curl -fsSL "$reg/@norskvideo%2Fnorsk-studio" | jq -r '."dist-tags".nightly')"
+          [ -n "$new_studio_lib" ] && [ "$new_studio_lib" != "null" ] || { echo "could not resolve norsk-studio npm nightly"; exit 1; }
+          studio_line="${new_studio_lib%%-*}"   # e.g. 1.28.0 — keep the image on this line
+          old_studio_img="$(jq -r '.latest.studio | split(":")[1]' manifest.seed.json)"
+          new_studio_img="$(curl -fsSL "https://hub.docker.com/v2/repositories/norskvideo/norsk-studio/tags?page_size=100&ordering=last_updated" \
+            | jq -r '.results[].name' \
+            | grep -E "^${studio_line}-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9a-f]+$" | head -1 || true)"
+          [ -n "$new_studio_img" ] || { echo "no published norsk-studio image on the $studio_line line — npm/docker version lines have diverged"; exit 1; }
+          echo "studio lib:   $old_studio_lib -> $new_studio_lib"
+          echo "studio image: $old_studio_img -> $new_studio_img"
+          if [ "$old_studio_img" != "$new_studio_img" ]; then
+            git grep -lF "norskvideo/norsk-studio:$old_studio_img" -- . ':!bun.lock' \
+              | xargs -r sed -i "s|norskvideo/norsk-studio:$old_studio_img|norskvideo/norsk-studio:$new_studio_img|g"
+            changed=1
+          fi
+          if [ "$old_studio_lib" != "$new_studio_lib" ]; then
+            git grep -lF "$old_studio_lib" -- . ':!bun.lock' | xargs -r sed -i "s|$old_studio_lib|$new_studio_lib|g"
+            changed=1
+          fi
+          # One studio entry, not two — the launched image tag is the runtime-
+          # relevant one; only fall back to the lib tag if the image held but the
+          # library advanced (npm nightly moved with no new image on the line yet).
+          if [ "$old_studio_img" != "$new_studio_img" ]; then
+            parts+=("studio \`$new_studio_img\`")
+          elif [ "$old_studio_lib" != "$new_studio_lib" ]; then
+            parts+=("studio-lib \`$new_studio_lib\`")
+          fi
+
+          # --- ctl daemon pin (flake.nix) -----------------------------------
+          # The pinned norsk-ctl in the dev flake is dev-only (CI downloads the
+          # released binary directly), but keep it fresh too. Bump ctlVersion +
+          # the four per-platform hashes to the `latest` channel. Mirrors
+          # packages/dev-kit/build/refresh-ctl-pin.sh in the ctl monorepo.
+          ctl_base="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+          old_ctl="$(grep -oE 'ctlVersion = "[^"]+"' flake.nix | sed -E 's/.*"(.*)"/\1/')"
+          new_ctl="$(curl -fsSL "$ctl_base/latest")"
+          if [ -n "$new_ctl" ] && [ "$old_ctl" != "$new_ctl" ]; then
+            declare -A ctlplat=([x86_64-linux]=linux-x64 [aarch64-linux]=linux-arm64 [aarch64-darwin]=darwin-arm64 [x86_64-darwin]=darwin-x64)
+            for sys in "${!ctlplat[@]}"; do
+              p="${ctlplat[$sys]}"
+              hex="$(curl -fsSL "$ctl_base/$new_ctl/norsk-ctl-$new_ctl-$p.sha256" | awk '{print $1}')"
+              [ -n "$hex" ] || { echo "no sha256 sidecar for $p"; exit 1; }
+              sri="$(nix hash convert --hash-algo sha256 --to sri "$hex")"
+              perl -0pi -e "s{(plat = \"$p\";\\s*hash = \")[^\"]*(\")}{\${1}$sri\${2}}" flake.nix
+            done
+            perl -0pi -e "s{(ctlVersion = \")[^\"]*(\")}{\${1}$new_ctl\${2}}" flake.nix
+            echo "ctl: $old_ctl -> $new_ctl"
+            changed=1
+            parts+=("norsk-ctl \`$new_ctl\`")
+          fi
+
+          # Join the moved components; empty when nothing changed (the dashboard
+          # then shows a clean green "nightly" cell with no detail).
+          summary=""
+          if [ ${#parts[@]} -gt 0 ]; then
+            summary="$(printf '%s, ' "${parts[@]}")"
+            summary="${summary%, }"
+          fi
+          {
+            echo "changed=$changed"
+            echo "summary=$summary"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Refresh the lockfile against the new pins
+        if: steps.bump.outputs.changed == '1'
+        run: nix develop .#build --command bash -c 'set -euo pipefail; bun install'
+
+      - name: Commit the bump to main
+        if: steps.bump.outputs.changed == '1'
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "chore: bump Norsk nightly + ctl pins to latest channel
+
+          ${{ steps.bump.outputs.summary }}
+
+          Coupled Norsk pins (npm overrides + manifest.seed.json image tags +
+          version-pin guard test) moved together via a global version-string
+          replace; lockfile regenerated. Dev flake norsk-ctl pin (version + 4
+          platform hashes) rebumped to the latest channel."
+          # main can advance under a long bump (lockfile regen + registry
+          # lookups run for minutes); a bare push then loses a non-fast-forward
+          # race and reds the nightly. Rebase-and-retry so an unrelated commit
+          # 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
+            echo "push rejected (attempt $attempt) - rebasing onto latest origin/main"
+            git fetch origin main
+            git rebase origin/main || { git rebase --abort; echo "rebase hit a real conflict; aborting"; exit 1; }
+          done
+          echo "push still failing after 5 rebase attempts"; exit 1
+
+      - name: Report "already fresh"
+        if: steps.bump.outputs.changed != '1'
+        run: echo "Nightly pins already current — nothing to bump."
+
+  # Report the nightly bump result to the aggregated product CI dashboard
+  # (id3as/ci-workflows). always() so a failed bump shows a sad pony; the summary
+  # rides along as the cell detail.
+  notify:
+    needs: bump
+    if: always()
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+      - id: meta
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
+            echo "state=failure" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=success" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: ./.github/actions/ci-status-dispatch
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          product: __PRODUCT__
+          pipeline: nightly
+          status: ${{ steps.meta.outputs.state }}
+          detail: ${{ needs.bump.outputs.summary }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "exports": {
     "./package.json": "./package.json"