@norskvideo/ctl-dev-kit 0.1.26 → 0.1.28

package/conventions/build-image.yml

@@ -0,0 +1,184 @@
+# Build + publish a PRODUCT container image, multi-arch (linux/amd64 +
+# linux/arm64), to Docker Hub. Single-sourced in @norskvideo/ctl-dev-kit
+# (conventions/build-image.yml) and drift-gated -- edit the dev-kit source, never
+# the copy.
+#
+# Multi-arch house style: native build per arch (no QEMU), each arch pushes its
+# own `:<label>-<arch>` tag to Docker Hub, then a publish job combines them with
+# `docker buildx imagetools create` into the multi-arch manifest. Each publish
+# writes two tags:
+#   <repo>:<label>    immutable, label = YYYY-MM-DD-<sha8> (what deployments pin)
+#   <repo>:<channel>  moving (latest | rc | nightly)
+#
+# The one per-repo value is the masked PUBLISH_IMAGE env: set to a product's
+# Docker Hub repo (norskvideo org) it builds + publishes both arches; left empty
+# the build runs as a standalone-build proof (both arches) and publishes nothing
+# -- for a product that is not deployed yet.
+#
+# CHANNEL: push-to-main publishes `latest` (matches the retired in-monorepo
+# pipeline, so :latest + the dated tags stay fresh for installers/deployments).
+# workflow_dispatch can publish any channel. When the product channel model
+# (rc -> latest promotion) lands, flip the push default to `nightly` and let the
+# promotion gate move `latest`.
+#
+# Repo-local for now; to be hoisted into id3as/ci-workflows as a reusable
+# workflow (RFC 0001 Workstream E).
+name: build-image
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      channel:
+        description: "Moving channel tag to publish (latest | rc | nightly)."
+        type: string
+        default: latest
+      dry_run:
+        description: "Build + stage both arches, skip the Docker Hub publish."
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # The Docker Hub repo this product publishes to (norskvideo org, e.g.
+  # norskvideo/norsk-<product>-product). Empty string = build-only proof, no
+  # publish (a product not yet deployed). This is the one per-repo env the drift
+  # gate masks; set it in the product repo, never in the dev-kit canonical.
+  PUBLISH_IMAGE: ""
+
+jobs:
+  # Compute the immutable label ONCE, so both arch builds and the manifest share
+  # it (a per-job `date` could straddle midnight and disagree).
+  label:
+    runs-on: x64
+    outputs:
+      label: ${{ steps.gen.outputs.label }}
+      channel: ${{ steps.gen.outputs.channel }}
+      # `publish` is derived here (in a step, where the env context is readable)
+      # because the env context is NOT available in a job-level `if:` -- the
+      # publish job gates on this output instead of on PUBLISH_IMAGE directly.
+      publish: ${{ steps.gen.outputs.publish }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+      - id: gen
+        run: |
+          label="$(date -u +%Y-%m-%d)-$(git rev-parse --short=8 HEAD)"
+          channel="${{ github.event.inputs.channel || 'latest' }}"
+          if [ -n "${PUBLISH_IMAGE}" ]; then publish=true; else publish=false; fi
+          echo "label=${label}" >> "$GITHUB_OUTPUT"
+          echo "channel=${channel}" >> "$GITHUB_OUTPUT"
+          echo "publish=${publish}" >> "$GITHUB_OUTPUT"
+          echo "label=${label} channel=${channel} publish=${publish}"
+
+  build:
+    needs: label
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: x64
+            arch: amd64
+          - runner: ar-arm-vm
+            arch: arm64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      # clean: false -- the integration suite (shared pool) leaves root-owned
+      # bind-mount dirs under test-temp/ that a non-root git clean can't remove
+      # (EACCES). This job never needs them; skip the clean so it doesn't choke on
+      # another workflow's leftovers.
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+
+      - name: Build product image (copy-only, via the dev-kit driver, native ${{ matrix.arch }})
+        run: |
+          if [ -n "${PUBLISH_IMAGE}" ]; then
+            IMAGE_TAG="${PUBLISH_IMAGE}:${{ needs.label.outputs.label }}-${{ matrix.arch }}"
+          else
+            IMAGE_TAG="norsk-ctl-product:${{ needs.label.outputs.label }}-${{ matrix.arch }}"
+          fi
+          echo "IMAGE_TAG=${IMAGE_TAG}" >> "$GITHUB_ENV"
+          export IMAGE_TAG
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install --frozen-lockfile
+            bun run build:image
+          '
+
+      - name: Log in to Docker Hub
+        if: ${{ env.PUBLISH_IMAGE != '' }}
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          username: norskvideo
+          password: ${{ secrets.DOCKER_PAT }}
+
+      - name: Push the per-arch image to Docker Hub
+        if: ${{ env.PUBLISH_IMAGE != '' }}
+        run: docker push "$IMAGE_TAG"
+
+  # Combine the per-arch images into a multi-arch manifest and write the two
+  # published tags. Skipped for a build-only product (empty PUBLISH_IMAGE) and on
+  # a dry run.
+  publish:
+    needs: [label, build]
+    if: ${{ needs.label.outputs.publish == 'true' && !inputs.dry_run }}
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          username: norskvideo
+          password: ${{ secrets.DOCKER_PAT }}
+
+      - name: Create + push the multi-arch manifest (dated label + channel)
+        run: |
+          label="${{ needs.label.outputs.label }}"
+          channel="${{ needs.label.outputs.channel }}"
+          # buildx imagetools create, not `docker manifest create`: the arm64
+          # runner's containerd image store pushes single-arch images wrapped in
+          # an OCI index, which `docker manifest create` refuses to nest. imagetools
+          # accepts index sources and writes every -t tag in one push.
+          docker buildx imagetools create \
+            -t "${PUBLISH_IMAGE}:${label}" \
+            -t "${PUBLISH_IMAGE}:${channel}" \
+            "${PUBLISH_IMAGE}:${label}-amd64" \
+            "${PUBLISH_IMAGE}:${label}-arm64"
+
+  # Report this pipeline's result to the aggregated product CI dashboard
+  # (id3as/ci-workflows) instead of posting its own pony -- the dashboard renders
+  # the pony/emoji from the dispatched result. always() so a red or manual run
+  # still reports.
+  notify:
+    needs: [build, publish]
+    if: ${{ !cancelled() }}
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+      - 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: build-image
+          status: ${{ steps.meta.outputs.state }}

package/conventions/check-drift.ts

@@ -54,10 +54,23 @@ function firstDiffLine(actual: string, expected: string): string {
 export const PRODUCT_LINE = /^(\s*product:\s*).*$/gm;
 export const PRODUCT_SENTINEL = "__PRODUCT__";
 
-function workflowProblem(relPath: string, canonicalRef: string, 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}`);
+// build-image.yml carries a second per-repo line: the Docker Hub repo the built
+// image is published to (empty on a build-only product). Masked like product:,
+// but — unlike product: — an empty value is a valid filled state, so it has no
+// unfilled-sentinel check.
+export const PUBLISH_IMAGE_LINE = /^(\s*PUBLISH_IMAGE:\s*).*$/gm;
+
+function workflowProblem(
+  relPath: string,
+  canonicalRef: string,
+  actual: string,
+  canonical: string,
+  maskLines: RegExp[] = [PRODUCT_LINE],
+): string | undefined {
+  // Compare structure with every per-repo value masked so any real value passes,
+  // then separately reject a copy that still carries the unfilled product:
+  // sentinel.
+  const mask = (s: string) => maskLines.reduce((acc, re) => acc.replace(re, `$1${PRODUCT_SENTINEL}`), s);
   if (mask(actual) !== mask(canonical)) {
     return `${relPath} has drifted from @norskvideo/ctl-dev-kit ${canonicalRef} (${firstDiffLine(mask(actual), mask(canonical))}). ${RESYNC}`;
   }
@@ -225,6 +238,7 @@ export interface CanonicalBytes {
   dprint: string;
   buildImageBootstrap: string;
   gitignoreCore: string;
+  buildImage: string;
 }
 
 // A file that must be a verbatim, byte-for-byte copy of its dev-kit canonical.
@@ -329,6 +343,29 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     push(workflowProblem(checksRel, "conventions/checks.yml", readFileSync(checksPath, "utf8"), canonical.checks));
   }
 
+  // build-image.yml is REQUIRED — every product builds its image in CI (a
+  // standalone-build proof), and a deployed one publishes it to Docker Hub. Two
+  // lines are per-repo: the notify job's `product:` dispatch key and the
+  // PUBLISH_IMAGE env (the Docker Hub repo, or empty for a build-only product);
+  // both are masked.
+  const buildImageYmlPath = join(repoRoot, ".github", "workflows", "build-image.yml");
+  const buildImageYmlRel = ".github/workflows/build-image.yml";
+  if (!existsSync(buildImageYmlPath)) {
+    problems.push(
+      `${buildImageYmlRel} not found (${buildImageYmlPath}). Copy conventions/build-image.yml from @norskvideo/ctl-dev-kit, set \`product:\` to this repo's dashboard key, and set PUBLISH_IMAGE to its Docker Hub repo (empty for a build-only product).`,
+    );
+  } else {
+    push(
+      workflowProblem(
+        buildImageYmlRel,
+        "conventions/build-image.yml",
+        readFileSync(buildImageYmlPath, "utf8"),
+        canonical.buildImage,
+        [PRODUCT_LINE, PUBLISH_IMAGE_LINE],
+      ),
+    );
+  }
+
   // 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.
@@ -392,6 +429,7 @@ if (import.meta.main) {
     dprint: readFileSync(join(import.meta.dir, "dprint.base.jsonc"), "utf8"),
     buildImageBootstrap: readFileSync(join(import.meta.dir, "..", "build", "build-image.bootstrap.sh"), "utf8"),
     gitignoreCore: readFileSync(join(import.meta.dir, "gitignore.core"), "utf8"),
+    buildImage: readFileSync(join(import.meta.dir, "build-image.yml"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical);
   if (report.ok) {

package/conventions/sync-drift.ts

@@ -30,6 +30,7 @@ import {
   GITIGNORE_END,
   PRODUCT_LINE,
   PRODUCT_SENTINEL,
+  PUBLISH_IMAGE_LINE,
   splitAtMarkers,
 } from "./check-drift.ts";
 
@@ -64,6 +65,32 @@ function syncWorkflow(repoRoot: string, rel: string, canonical: string, r: SyncR
   writeIfChanged(path, canonical.replace(PRODUCT_LINE, `$1${key}`), rel, r.written);
 }
 
+// build-image.yml: canonical byte-for-byte except two per-repo lines — the
+// notify job's `product:` dispatch key and the PUBLISH_IMAGE env (the Docker Hub
+// repo, or empty for a build-only product). Re-emit the canonical with both of
+// the repo's own values restored. A copy with no product key to preserve (absent
+// or still the sentinel) is left for the gate to flag. PUBLISH_IMAGE is restored
+// via a function replacer so a value containing `$` can't be read as a
+// replacement backreference.
+function syncBuildImage(repoRoot: string, canonical: string, r: SyncReport): void {
+  const rel = ".github/workflows/build-image.yml";
+  const path = join(repoRoot, rel);
+  if (!existsSync(path)) {
+    r.skipped.push(`${rel} (absent)`);
+    return;
+  }
+  const existing = readFileSync(path, "utf8");
+  const key = existing.match(/^\s*product:\s*(\S+)/m)?.[1];
+  if (!key || key === PRODUCT_SENTINEL) {
+    r.skipped.push(`${rel} (no product: key to preserve)`);
+    return;
+  }
+  const publishLine = existing.match(/^\s*PUBLISH_IMAGE:.*$/m)?.[0];
+  let out = canonical.replace(PRODUCT_LINE, `$1${key}`);
+  if (publishLine !== undefined) out = out.replace(PUBLISH_IMAGE_LINE, () => publishLine);
+  writeIfChanged(path, out, rel, r.written);
+}
+
 // flake.nix is verbatim except the dev-only ctl pin (ctlVersion + the four
 // per-platform hashes), which floats per repo. Re-emit canonical STRUCTURE with
 // the repo's pin restored in order — so a structural edit (e.g. a stray comment)
@@ -152,6 +179,7 @@ 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);
+  syncBuildImage(repoRoot, canonical.buildImage, r);
 
   // publish-docs.yml is optional and verbatim (no per-repo line) — only re-sync a
   // repo that already carries it, unlike biome/tsconfig which every repo must have.
@@ -183,6 +211,7 @@ if (import.meta.main) {
     dprint: readFileSync(join(dir, "dprint.base.jsonc"), "utf8"),
     buildImageBootstrap: readFileSync(join(dir, "..", "build", "build-image.bootstrap.sh"), "utf8"),
     gitignoreCore: readFileSync(join(dir, "gitignore.core"), "utf8"),
+    buildImage: readFileSync(join(dir, "build-image.yml"), "utf8"),
   };
   const report = syncDrift(repoRoot, canonical);
   if (report.written.length === 0) {

package/create-product/canon.ts

@@ -23,6 +23,7 @@ export interface Canon {
   tsconfigBase: string;
   dprint: string;
   buildImageBootstrap: string;
+  buildImage: string;
   gitignoreCore: string;
   invariantsTemplate: string;
 }
@@ -39,6 +40,7 @@ export function loadCanon(): Canon {
     tsconfigBase: readFileSync(join(conventionsDir, "tsconfig.base.json"), "utf8"),
     dprint: readFileSync(join(conventionsDir, "dprint.base.jsonc"), "utf8"),
     buildImageBootstrap: readFileSync(join(buildDir, "build-image.bootstrap.sh"), "utf8"),
+    buildImage: readFileSync(join(conventionsDir, "build-image.yml"), "utf8"),
     gitignoreCore: readFileSync(join(conventionsDir, "gitignore.core"), "utf8"),
     invariantsTemplate: readFileSync(join(import.meta.dir, "..", "testing", "INVARIANTS.template.md"), "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/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) },
     { 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.26",
+  "version": "0.1.28",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",