@norskvideo/ctl-dev-kit 0.1.16 → 0.1.18

package/build/flake.nix

@@ -20,7 +20,7 @@
   description = "norsk-ctl product build + dev shell";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/d233902339c02a9c334e7e593de68855ad26c4cb"; # nixpkgs-unstable 2026-05-15, bun 1.3.13
+    nixpkgs.url = "github:NixOS/nixpkgs/d233902339c02a9c334e7e593de68855ad26c4cb"; # nixpkgs-unstable 2026-05-15, bun 1.3.13, chromium 148.0.7778.167
     # Biome must match the version pinned in package.json (@biomejs/biome 2.5.5)
     # exactly: 2.4.x can't parse this repo's biome.json (`rules.preset` is a
     # 2.5 key) and any other 2.5.x emits a version-mismatch info that breaks the
@@ -92,22 +92,49 @@
             pkgs.git
             pkgs.ffmpeg # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
           ];
+
+          # Playwright doc-guide browser. nix-pinned headless Chromium needs a
+          # real X display on a truly headless box (page.fill silently no-ops on
+          # plain HTML inputs; some pages crash the renderer). Ubuntu's apt Xvfb
+          # is too old for Chromium 148's input dispatch — the nix xorg-server
+          # works. A product's scripts/with-display.sh wraps playwright in
+          # xvfb-run iff DISPLAY is unset.
+          linuxBrowser = pkgs.lib.optionals pkgs.stdenv.isLinux [
+            pkgs.chromium
+            pkgs.xvfb-run
+            pkgs.xorg.xorgserver
+          ];
+          # Headless Chromium finds no system fonts on NixOS, so text renders at
+          # zero advance width — invisible, and every toBeVisible() on text times
+          # out. Point fontconfig at a minimal bundled set so glyphs have real
+          # metrics.
+          fontsConf = pkgs.makeFontsConf {
+            fontDirectories = [ pkgs.dejavu_fonts pkgs.liberation_ttf ];
+          };
+          browserHook = pkgs.lib.optionalString pkgs.stdenv.isLinux ''
+            export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
+            export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+            export FONTCONFIG_FILE=${fontsConf}
+          '';
         in {
           # Everyday dev shell — build tools + the pinned norsk-ctl daemon.
           # `nix develop` and `nix develop .#dev` are equivalent.
           default = pkgs.mkShell {
             BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools ++ [ (mkCtl system) ];
+            buildInputs = buildTools ++ linuxBrowser ++ [ (mkCtl system) ];
+            shellHook = browserHook;
           };
           dev = pkgs.mkShell {
             BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools ++ [ (mkCtl system) ];
+            buildInputs = buildTools ++ linuxBrowser ++ [ (mkCtl system) ];
+            shellHook = browserHook;
           };
           # Lean shell for CI (build-image / integration) — no ctl fetch, so
           # image builds never depend on the ctl binary channel.
           build = pkgs.mkShell {
             BIOME_BINARY = "${biome}/bin/biome";
-            buildInputs = buildTools;
+            buildInputs = buildTools ++ linuxBrowser;
+            shellHook = browserHook;
           };
         });
     };

package/conventions/check-drift.ts

@@ -211,6 +211,7 @@ export interface CanonicalBytes {
   core: string;
   flake: string;
   upgradeLatest: string;
+  syncDevKit: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -336,6 +337,22 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     );
   }
 
+  // sync-dev-kit.yml is OPTIONAL for the same reason as upgrade-latest.yml — a
+  // product may not carry it yet — but when present it is the shared,
+  // single-sourced workflow that keeps this repo's dev-kit pin fresh, and must
+  // not diverge. Only its `product:` dispatch key is per-repo.
+  const syncPath = join(repoRoot, ".github", "workflows", "sync-dev-kit.yml");
+  if (existsSync(syncPath)) {
+    push(
+      workflowProblem(
+        ".github/workflows/sync-dev-kit.yml",
+        "conventions/sync-dev-kit.yml",
+        readFileSync(syncPath, "utf8"),
+        canonical.syncDevKit,
+      ),
+    );
+  }
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -345,6 +362,7 @@ if (import.meta.main) {
     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"),
+    syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),

package/conventions/sync-dev-kit.yml

@@ -0,0 +1,181 @@
+# Keep this product's shared conventions fresh against @norskvideo/ctl-dev-kit.
+# The dev-kit single-sources the files every ctl product would otherwise
+# copy-and-drift (the fenced CLAUDE.md core, flake.nix, the biome/tsconfig/dprint
+# bases, the shared workflows, the build bootstrap). check:drift fails CI when a
+# copy diverges from the *installed* dev-kit — so a product goes stale two ways:
+# its pin lags the newest published dev-kit, and once the pin bumps its copies
+# need re-syncing. This workflow closes the first gap and surfaces the second.
+#
+# It bumps the @norskvideo/ctl-dev-kit pin to the newest published version,
+# reinstalls, and runs this product's own gate (check:drift + lint + typecheck +
+# unit tests) against the new bytes:
+#
+#   - gate green -> a clean freshness bump; commit straight to main, like
+#     upgrade-latest.yml. The common case: a dev-kit release that doesn't touch
+#     this product's copies (or only verbatim ones already reconciled).
+#   - gate red   -> the new dev-kit needs a human: a drifted copy to re-sync, or
+#     a convention change that breaks this product. Push a branch and open a PR;
+#     check:drift's own output names each drifted file and the first diffing line.
+#     Re-sync on the branch until green, then merge.
+#
+# The re-sync is deliberately NOT automated. check:drift already emits the exact
+# fix, the masked / marker-block copies (the flake ctl pin, the CLAUDE core, the
+# dprint and gitignore blocks) need judgement, and a bot that blindly rewrote
+# them could commit a subtly-wrong splice. Detection plus a ready branch is the
+# leverage; the fix stays human.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/sync-dev-kit.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: sync-dev-kit
+
+on:
+  schedule:
+    - cron: "37 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Resolve the newest published dev-kit and bump the pin
+        id: sync
+        run: |
+          set -euo pipefail
+          reg="https://registry.npmjs.org"
+          pkg="@norskvideo/ctl-dev-kit"
+          enc="@norskvideo%2Fctl-dev-kit"
+
+          # The runner has no npm; read the dist-tag off the registry with curl+jq
+          # (same as upgrade-latest.yml resolves the Norsk nightly).
+          new="$(curl -fsSL "$reg/$enc" | jq -r '."dist-tags".latest')"
+          [ -n "$new" ] && [ "$new" != "null" ] || { echo "could not resolve $pkg latest"; exit 1; }
+
+          # The current pin, whatever its range operator. A repo with no dev-kit
+          # dep has nothing to sync.
+          old="$(grep -oE "\"$pkg\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" package.json | head -1 | sed -E 's/.*"([^"]*)"$/\1/')"
+          if [ -z "$old" ]; then
+            echo "$pkg is not pinned in package.json -- nothing to sync."
+            echo "changed=0" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          old_bare="${old#^}"; old_bare="${old_bare#~}"
+          echo "dev-kit: $old -> ^$new"
+          if [ "$old_bare" = "$new" ]; then
+            echo "already on the newest dev-kit ($new)."
+            echo "changed=0" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # Surgical single-line rewrite so package.json keeps its formatting
+          # (a jq reserialize would reflow the whole file and trip the formatter).
+          sed -i -E "s|(\"$pkg\"[[:space:]]*:[[:space:]]*\")[^\"]*(\")|\1^$new\2|" package.json
+          echo "changed=1" >> "$GITHUB_OUTPUT"
+          echo "old=$old_bare" >> "$GITHUB_OUTPUT"
+          echo "new=$new" >> "$GITHUB_OUTPUT"
+
+      - name: Reinstall and run the product gate against the new dev-kit
+        id: gate
+        if: steps.sync.outputs.changed == '1'
+        continue-on-error: true
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install
+            bun run check:drift
+            bun run lint
+            bun run typecheck
+            bun run test:unit
+          '
+
+      - name: Land the freshness bump on main (gate green)
+        if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'success'
+        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: sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }}
+
+          @norskvideo/ctl-dev-kit pin bumped to the newest published version;
+          check:drift + lint + typecheck + unit tests green against the new bytes.
+          Lockfile regenerated."
+          # A GITHUB_TOKEN push does not retrigger checks (Actions' recursion
+          # guard) -- fine, the gate above already ran them. 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
+            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: Open a reconciliation PR (gate red)
+        if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          branch="sync-dev-kit/${{ steps.sync.outputs.new }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add -A
+          git commit -m "chore: sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }} (needs reconciliation)"
+          git push -f origin "$branch"
+          title="Sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }}"
+          body="$(printf '%s\n' \
+            "Automated dev-kit sync: the @norskvideo/ctl-dev-kit pin moved to the newest" \
+            "published version, but this product's gate is **red** against the new bytes," \
+            "so the sync needs a human." \
+            "" \
+            "Run the gate locally to see what to fix:" \
+            "" \
+            "    bun install" \
+            "    bun run check:drift   # names each drifted copy and the first diffing line" \
+            "    bun run lint && bun run typecheck && bun run test:unit" \
+            "" \
+            "Re-sync the named copies from node_modules/@norskvideo/ctl-dev-kit (never" \
+            "hand-edit against memory), or resolve the convention change this pin" \
+            "introduced, pushing to this branch until green -- then merge.")"
+          if existing="$(gh pr list --head "$branch" --state open --json number -q '.[0].number')" && [ -n "$existing" ]; then
+            gh pr edit "$existing" --title "$title" --body "$body"
+          else
+            gh pr create --base main --head "$branch" --title "$title" --body "$body"
+          fi
+
+      - name: Report "already fresh"
+        if: steps.sync.outputs.changed != '1'
+        run: echo "dev-kit pin already current -- nothing to sync."
+
+  # Report the sync result to the aggregated product CI dashboard
+  # (id3as/ci-workflows). always() so a failed sync shows a sad pony. A gate-red
+  # run that opened a PR is still a successful sync -- the red lives on the PR's
+  # own checks run, not here.
+  notify:
+    needs: sync
+    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: dev-kit
+          status: ${{ steps.meta.outputs.state }}

package/create-product/canon.ts

@@ -17,6 +17,7 @@ export interface Canon {
   flake: string;
   flakeLock: string;
   upgradeLatest: string;
+  syncDevKit: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -32,6 +33,7 @@ export function loadCanon(): Canon {
     flake: readFileSync(join(buildDir, "flake.nix"), "utf8"),
     flakeLock: readFileSync(join(buildDir, "flake.lock"), "utf8"),
     upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
+    syncDevKit: readFileSync(join(conventionsDir, "sync-dev-kit.yml"), "utf8"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
     biome: readFileSync(join(conventionsDir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(conventionsDir, "tsconfig.base.json"), "utf8"),

package/create-product/create-product.ts

@@ -110,6 +110,7 @@ function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[]
     },
     { path: ".github/workflows/checks.yml", content: fillProduct(canon.checks) },
     { path: ".github/workflows/upgrade-latest.yml", content: fillProduct(canon.upgradeLatest) },
+    { path: ".github/workflows/sync-dev-kit.yml", content: fillProduct(canon.syncDevKit) },
     { path: ".github/actions/ci-status-dispatch/action.yml", content: loadAsset("ci-status-dispatch.yml") },
     { path: "manifest.seed.json", content: seedJson(ctx) },
     { path: "deployment/build-image.sh", content: buildImageWrapper(ctx), executable: true },

package/package.json

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