@norskvideo/ctl-dev-kit 0.1.66 → 0.1.68

package/conventions/check-drift.ts

@@ -238,6 +238,9 @@ export interface CanonicalBytes {
   flake: string;
   upgradeLatest: string;
   syncDevKit: string;
+  /** 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;
   publishDocs: string;
   /** conventions/build-docs.yml — the embedded docs variant (bundle -> image, no upload). */
   buildDocs: string;
@@ -513,6 +516,14 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     );
   }
 
+  // sync-ctl-packages.yml is OPTIONAL until a repo has been synced once — it is
+  // NEW, and sync-drift creates it. Unlike its neighbours it carries no per-repo
+  // line (it dispatches to no dashboard), so the whole file is canonical.
+  const syncCtlPath = join(repoRoot, ".github", "workflows", "sync-ctl-packages.yml");
+  if (existsSync(syncCtlPath) && readFileSync(syncCtlPath, "utf8") !== canonical.syncCtlPackages) {
+    push(`.github/workflows/sync-ctl-packages.yml differs from conventions/sync-ctl-packages.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
@@ -569,6 +580,7 @@ if (import.meta.main) {
     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"),
+    syncCtlPackages: readFileSync(join(import.meta.dir, "sync-ctl-packages.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),

package/conventions/sync-ctl-packages.yml

@@ -0,0 +1,162 @@
+# Keep this product fresh against the ctl-* npm family: the test harness that
+# drives its smoke and integration tiers, the SDK, the foundation helpers and
+# the product-template schema.
+#
+# sync-dev-kit already does this for the conventions package, and upgrade-latest
+# does it for the Norsk nightly line. Nothing did it for the rest, so the pins
+# drifted silently: on 2026-08-30 studio carried a conventions pin bumped that
+# morning beside an SDK three releases behind, and three repos ran three
+# different vintages of the same smoke runner. The caret ranges admit the new
+# versions -- `--frozen-lockfile` is what holds them back, and nothing ever
+# regenerated the lockfile.
+#
+# Unlike sync-dev-kit this NEVER pushes to main. Its gate is drift + lint +
+# typecheck + unit, and a bump to the test harness changes the code that drives
+# smoke and integration -- neither of which that gate runs, because both need
+# Docker and a licence. A green gate therefore proves strictly less here than it
+# does for a conventions bump, so the bump goes to a human as a PR. A red gate
+# still opens one, as a draft: adopting a breaking change is real engineering,
+# not a copy-paste, and the PR is where that work belongs.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/sync-ctl-packages.yml)
+# and copied verbatim into each product repo; the check:drift gate fails CI if a
+# copy diverges. Never hand-edit the copy -- edit the source and re-sync.
+name: sync-ctl-packages
+
+on:
+  schedule:
+    # Clear of sync-dev-kit's 04:37 so the two never race the same lockfile.
+    - cron: "52 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: sync-ctl-packages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: x64
+    steps:
+      # CI_DISPATCH_TOKEN, not the automatic GITHUB_TOKEN: a PR opened by
+      # GITHUB_TOKEN raises no workflow runs, so the product's own build, smoke
+      # and integration would never execute against the new pins -- which is the
+      # entire reason for opening it. clean: false for the same reason as the
+      # other shared jobs: the suites leave root-owned bind-mount dirs under
+      # test-temp/ that a non-root git clean cannot remove.
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          clean: false
+
+      - name: Resolve the newest published ctl-* packages and rewrite the pins
+        id: bump
+        run: |
+          set -euo pipefail
+          reg="https://registry.npmjs.org"
+          # The conventions package is deliberately absent: sync-dev-kit owns it,
+          # lands it straight to main, and re-syncs the copied files with it.
+          family="ctl-test-harness ctl-sdk ctl-foundation ctl-product-template-schema"
+
+          # Every tracked package.json, not just the root: a repo can pin the
+          # same package in a nested workspace (playout pins the harness twice),
+          # and a root-only rewrite would split the line across the two.
+          mapfile -t manifests < <(git ls-files '*package.json' ':!:**/node_modules/**')
+
+          moved=""
+          for short in $family; do
+            pkg="@norskvideo/$short"
+            enc="@norskvideo%2F$short"
+            # The runner has no npm; read the dist-tag off the registry with
+            # curl+jq, as sync-dev-kit and upgrade-latest both do.
+            new="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$reg/$enc" | jq -r '."dist-tags".latest')"
+            [ -n "$new" ] && [ "$new" != "null" ] || { echo "could not resolve $pkg latest"; exit 1; }
+
+            for m in "${manifests[@]}"; do
+              old="$(grep -oE "\"$pkg\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$m" | head -1 | sed -E 's/.*"([^"]*)"$/\1/' || true)"
+              # Absent here, or a workspace protocol spec that names no version.
+              case "$old" in "" | workspace:*) continue ;; esac
+              old_bare="${old#^}"; old_bare="${old_bare#~}"
+              [ "$old_bare" != "$new" ] || continue
+              # Surgical single-line rewrite so the file keeps its formatting;
+              # a jq reserialize would reflow it and trip the formatter.
+              sed -i -E "s|(\"$pkg\"[[:space:]]*:[[:space:]]*\")[^\"]*(\")|\1^$new\2|" "$m"
+              echo "$m: $pkg $old -> ^$new"
+              moved="$moved- \`$pkg\` $old -> \`^$new\` ($m)"$'\n'
+            done
+          done
+
+          if [ -z "$moved" ]; then
+            echo "every ctl-* pin is already on its newest published version."
+            echo "changed=0" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=1" >> "$GITHUB_OUTPUT"
+            { echo "moved<<PINS"; printf '%s' "$moved"; echo "PINS"; } >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Reinstall and run the product gate
+        id: gate
+        if: steps.bump.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: Open (or update) the pin-freshness PR
+        if: steps.bump.outputs.changed == '1'
+        env:
+          GH_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+          GATE: ${{ steps.gate.outcome }}
+        run: |
+          set -euo pipefail
+          branch="chore/sync-ctl-packages"
+          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 the ctl-* pins to their newest published versions"
+          # One branch, force-pushed: a daily schedule must refresh the standing
+          # PR rather than accumulate a new one every morning.
+          git push -f origin "$branch"
+
+          if [ "$GATE" = "success" ]; then
+            verdict="Gate green: check:drift, lint, typecheck and unit tests all pass on the new pins."
+            draft=""
+          else
+            verdict="**Gate red** — the new pins do not fit this product as-is. Adopting them is real engineering, not a merge."
+            draft="--draft"
+          fi
+
+          body="$(cat <<EOF
+          Automated by \`sync-ctl-packages\`.
+
+          ## Pins moved
+
+          ${{ steps.bump.outputs.moved }}
+
+          ## What the gate proved
+
+          $verdict
+
+          It did **not** run smoke or integration — both need Docker and a licence.
+          A test-harness bump changes the code that drives those tiers, so the
+          runs raised on this PR are the real evidence. Read them before merging.
+          EOF
+          )"
+
+          if [ -z "$(gh pr list --head "$branch" --state open --json number --jq '.[].number')" ]; then
+            gh pr create $draft --head "$branch" --base main \
+              --title "chore: sync the ctl-* pins to their newest published versions" \
+              --body "$body"
+          else
+            gh pr edit "$branch" --body "$body"
+          fi

package/conventions/sync-drift.ts

@@ -223,6 +223,15 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   syncWorkflow(repoRoot, ".github/workflows/checks.yml", canonical.checks, r);
   syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
   syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
+  // No per-repo line to preserve, so it is written whole -- and CREATED where
+  // absent, unlike syncWorkflow's copies. That is how a repo acquires the
+  // workflow at all: its next sync run installs it.
+  writeIfChanged(
+    join(repoRoot, ".github/workflows/sync-ctl-packages.yml"),
+    canonical.syncCtlPackages,
+    ".github/workflows/sync-ctl-packages.yml",
+    r.written,
+  );
   syncBuildImage(repoRoot, canonical.buildImage, r);
   syncSmoke(repoRoot, canonical.smoke, r);
 
@@ -256,6 +265,7 @@ if (import.meta.main) {
     flake: readFileSync(join(dir, "..", "build", "flake.nix"), "utf8"),
     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"),
     publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(dir, "build-docs.yml"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),

package/create-product/canon.ts

@@ -18,6 +18,7 @@ export interface Canon {
   flakeLock: string;
   upgradeLatest: string;
   syncDevKit: string;
+  syncCtlPackages: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -39,6 +40,7 @@ export function loadCanon(): Canon {
     flakeLock: readFileSync(join(buildDir, "flake.lock"), "utf8"),
     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"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
     buildDocs: readFileSync(join(conventionsDir, "build-docs.yml"), "utf8"),
     biome: readFileSync(join(conventionsDir, "biome.base.json"), "utf8"),

package/create-product/create-product.ts

@@ -111,6 +111,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/workflows/sync-ctl-packages.yml", content: canon.syncCtlPackages },
     { 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/licence/check-template.ts

@@ -0,0 +1,117 @@
+// Lint a repo's licenceTemplate.json against what the repo actually is.
+//
+// The template is this repo's half of a licence: the `products[]` entries a
+// grant needs in order to entitle it. Minting composes {a grant's header} +
+// {the union of one or more repos' entries}, so a template that names the wrong
+// product — or an imageRef the build never produces — mints a licence that
+// entitles nothing, and the first sign is a 60-second readiness timeout.
+//
+// That is not hypothetical. licensing/partner-all-products-template.json is
+// hand-maintained, names four products, and has silently omitted both turnkeys
+// for as long as they have existed. This lint is what makes the derived
+// version impossible to get wrong the same way.
+//
+// It asserts recorded INTENT matches reality, not security: a user can retag
+// any image, so imageRef buys no defence. What it buys is a statement of what
+// was meant, which is only worth having if something keeps it true.
+import { readFileSync } from "node:fs";
+
+export interface RepoFacts {
+  /** The repo's own PRODUCT_NAME. */
+  product: string;
+  /** The image name CI builds under — see builtImageName. */
+  image: string;
+}
+
+/** The image name CI builds under, by CI's own rule: PUBLISH_IMAGE when set,
+ *  else the build script's IMAGE_TAG default, tag stripped. The licence matches
+ *  on the repo part alone (`imageRefMatches`: `parsed.repo !== entry.imageRef`),
+ *  so the tag never belongs in a template. */
+export function builtImageName(opts: { publishImage: string; buildDefault: string }): string | null {
+  const ref = opts.publishImage.trim() || opts.buildDefault.trim();
+  if (!ref) return null;
+  // Strip a tag, but not a registry port: a colon is a tag only after the last slash.
+  const lastSlash = ref.lastIndexOf("/");
+  const colon = ref.indexOf(":", lastSlash + 1);
+  return colon === -1 ? ref : ref.slice(0, colon);
+}
+
+const REQUIRED_ENTRY_FIELDS = ["product", "imageRef", "versionConstraint", "mode"] as const;
+
+/** Fields that describe WHO a licence was cut for. A repo does not know them,
+ *  and a merged staff licence that inherited one repo's expiry would be a
+ *  quiet, dated surprise. */
+const GRANT_ONLY_FIELDS = ["issuedTo", "email", "expiry", "timeout", "nonProduction"] as const;
+
+export function templateProblems(templateJson: string, repo: RepoFacts): string[] {
+  let parsed: { products?: unknown } & Record<string, unknown>;
+  try {
+    parsed = JSON.parse(templateJson);
+  } catch (e) {
+    return [`licenseTemplate.json is not valid JSON: ${String(e)}`];
+  }
+  if (typeof parsed !== "object" || parsed === null) return ["licenseTemplate.json is not an object"];
+
+  const problems: string[] = [];
+  for (const f of GRANT_ONLY_FIELDS) {
+    if (f in parsed) {
+      problems.push(`licenseTemplate.json carries "${f}", which belongs to the grant, not the repo — remove it`);
+    }
+  }
+  if (!Array.isArray(parsed.products)) {
+    problems.push('licenseTemplate.json has no "products" array');
+    return problems;
+  }
+
+  const entries = parsed.products as Record<string, unknown>[];
+  for (const [i, entry] of entries.entries()) {
+    for (const f of REQUIRED_ENTRY_FIELDS) {
+      if (typeof entry?.[f] !== "string") problems.push(`products[${i}] is missing "${f}"`);
+    }
+    const ref = entry?.imageRef;
+    if (typeof ref === "string") {
+      const lastSlash = ref.lastIndexOf("/");
+      if (ref.indexOf(":", lastSlash + 1) !== -1) {
+        problems.push(`products[${i}].imageRef "${ref}" carries a tag; a licence matches the repo part only`);
+      }
+    }
+  }
+
+  const named = entries.map((e) => e?.product).filter((p): p is string => typeof p === "string");
+  if (!named.includes(repo.product)) {
+    problems.push(
+      `licenseTemplate.json does not name this repo's product ${repo.product} (names: ${named.join(", ") || "nothing"})`,
+    );
+    return problems;
+  }
+
+  const mine = entries.find((e) => e?.product === repo.product);
+  if (typeof mine?.imageRef === "string" && mine.imageRef !== repo.image) {
+    problems.push(`products[].imageRef for ${repo.product} is "${mine.imageRef}" but this repo builds "${repo.image}"`);
+  }
+  return problems;
+}
+
+if (import.meta.main) {
+  const [file, product, image] = process.argv.slice(2);
+  if (!file || !product || !image) {
+    console.error("usage: check-template.ts <licenseTemplate.json> <product-name> <built-image-name>");
+    process.exit(2);
+  }
+  let contents: string;
+  try {
+    contents = readFileSync(file, "utf8");
+  } catch {
+    // Absence is not yet an error: the turnkeys' templates wait on their
+    // customer-facing image names being settled. Flipping this to a failure is
+    // a one-line change once every repo carries one.
+    console.log(`licence-template: no ${file} — not yet required in this repo`);
+    process.exit(0);
+  }
+  const problems = templateProblems(contents, { product, image });
+  if (problems.length) {
+    for (const p of problems) console.error(`licence-template: ${p}`);
+    process.exit(1);
+  }
+  console.log(`licence-template: ${file} names ${product} at ${image}`);
+}

package/package.json

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