@norskvideo/ctl-dev-kit 0.1.0

package/build/Dockerfile.bundle

@@ -0,0 +1,55 @@
+# Shared copy-only product-backend image for the "bundle" products
+# (probe / funke-pegasus / norsk-commentary / norsk-playout). Single-sourced in
+# @norskvideo/ctl-dev-kit so the four images cannot drift; the per-product facts
+# (tag, container port, optional native addon / assets) come in as build args and
+# staged directories from the shared build-bundle-image.sh driver.
+#
+# Studio is NOT built from this file — it ships a `bun build --compile` binary
+# with a different (STUDIO_ASSET_ROOT) layout; see products/studio/deployment.
+#
+# Copy-only: the backend bundle, frontend, dashboards, components, and the
+# optional native addon + product-template assets are all built/collected on the
+# host by the driver and COPYd in. Nothing is installed or compiled here (the old
+# per-product images ran `bun install` inside an oven/bun:alpine builder and
+# shipped the whole node_modules; the bundle inlines only what it reaches).
+#
+# The base is single-sourced in build/common.sh (PRODUCT_BASE_IMAGE) and passed
+# as BASE_IMAGE, so every product image shares one pinned distroless base (glibc
+# + libgcc/libstdc++, no shell). The runtime bun is imported Docker-natively from
+# the upstream slim image (BUN_IMAGE = oven/bun:<version>-slim): buildkit rejects
+# a variable in `COPY --from=${BUN_IMAGE}`, so it's aliased to a named stage from
+# the global-scope ARG and the binary COPYd out; that stage only donates a
+# prebuilt binary, so the final image stays copy-only.
+#
+# Split-level asset layout (the subtle part): the backend is a single bundled
+# file at backend/dist/index.js, so at runtime import.meta.dir is that bundle's
+# dir for ALL of the collapsed modules. server.ts's `../../frontend/dist` lands
+# beside the app dir, but lib/{components,dashboards,assets}.ts (originally under
+# backend/src/lib, one level deeper) kept `../../../{components/lib,dashboards,
+# assets}`, which resolve ONE level above the app dir. So dashboards +
+# components/lib + assets go at /usr/src while backend/frontend go under
+# /usr/src/app. A flat /usr/src/app layout silently drops them from the generated
+# product-template tars.
+ARG BASE_IMAGE
+ARG BUN_IMAGE
+FROM ${BUN_IMAGE} AS bun
+
+FROM ${BASE_IMAGE}
+# The container port docker-runner maps the host port to (probe/funke 4321,
+# commentary/playout 4322). Passed by the driver from the wrapper's PRODUCT_PORT.
+ARG PRODUCT_PORT=4321
+COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
+WORKDIR /usr/src/app
+COPY backend/dist ./backend/dist
+# Optional native addon(s), beside the bundle where <product>-identity.ts
+# createRequires them. The driver stages an empty native/ for products that ship
+# no signer (funke/commentary/playout), so this COPY is then a harmless no-op.
+COPY native/ ./backend/dist/
+COPY frontend/dist ./frontend/dist
+COPY dashboards /usr/src/dashboards
+COPY components/lib /usr/src/components/lib
+# Optional product-template assets (funke's slate/black PNGs). Empty otherwise.
+COPY assets /usr/src/assets
+ENV PORT=${PRODUCT_PORT}
+EXPOSE ${PRODUCT_PORT}
+CMD ["/usr/local/bin/bun", "run", "backend/dist/index.js"]

package/build/build-bundle-image.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Shared driver for the copy-only "bundle" product images
+# (probe / funke-pegasus / norsk-commentary / norsk-playout). Single-sourced in
+# @norskvideo/ctl-dev-kit; each product's deployment/build-image.sh is a thin
+# wrapper that sets the per-product facts and sources this file. Studio does NOT
+# use this driver (it ships a --compile binary; see products/studio/deployment).
+#
+# The wrapper MUST set before sourcing:
+#   PRODUCT_DIR   absolute path to the product workspace (backend/, frontend/,
+#                 dashboards/, components/, package.json)
+#   IMAGE_TAG     the image tag to build (the wrapper sets the product default)
+#   PRODUCT_PORT  the container port docker-runner maps to (probe/funke 4321,
+#                 commentary/playout 4322)
+# Optional:
+#   PRODUCT_BUILD_SCRIPT  workspace script that builds the host artifacts
+#                         (default: build:no-lint)
+#   BUN_VERSION           override the pinned bun (default from packageManager)
+#
+# Everything else is auto-detected off PRODUCT_DIR, so a product opts in just by
+# having the directory/script — no per-product flag to keep in sync:
+#   native/                    native addon(s) (probe's signer) -> beside bundle
+#   assets/                    product-template assets (funke's PNGs)
+#   scripts/runtime-images.ts  -> emits the norsk-ctl.runtime-images label
+set -euo pipefail
+
+: "${PRODUCT_DIR:?build-bundle-image.sh: PRODUCT_DIR must be set by the wrapper}"
+: "${IMAGE_TAG:?build-bundle-image.sh: IMAGE_TAG must be set by the wrapper}"
+: "${PRODUCT_PORT:?build-bundle-image.sh: PRODUCT_PORT must be set by the wrapper}"
+build_script="${PRODUCT_BUILD_SCRIPT:-build:no-lint}"
+
+driver_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./common.sh
+source "${driver_dir}/common.sh"
+
+# Pin bun once from the product repo's packageManager so downstream helpers don't
+# each re-walk the tree.
+export BUN_VERSION="${BUN_VERSION:-$(product_bun_version "${PRODUCT_DIR}")}"
+
+echo "==> building on host (${build_script})"
+bun run --cwd "${PRODUCT_DIR}" "${build_script}"
+
+stage="$(mktemp -d)"
+trap 'rm -rf "${stage}"' EXIT
+
+echo "==> staging artifacts"
+mkdir -p "${stage}/backend" "${stage}/frontend" "${stage}/components" "${stage}/native" "${stage}/assets"
+cp -R "${PRODUCT_DIR}/backend/dist" "${stage}/backend/dist"
+cp -R "${PRODUCT_DIR}/frontend/dist" "${stage}/frontend/dist"
+cp -R "${PRODUCT_DIR}/dashboards" "${stage}/dashboards"
+cp -R "${PRODUCT_DIR}/components/lib" "${stage}/components/lib"
+
+# Native addon(s): staged beside the bundle. Strip the build host's RUNPATH (nix
+# store / repo-local paths) so the shipped .node carries no build-host paths; its
+# NEEDED libs resolve via the base image's default search path. Best-effort:
+# only if patchelf is available.
+if [ -d "${PRODUCT_DIR}/native" ]; then
+  find "${PRODUCT_DIR}/native" -maxdepth 1 -name '*.node' -exec cp {} "${stage}/native/" \;
+  if command -v patchelf >/dev/null 2>&1; then
+    find "${stage}/native" -name '*.node' -exec patchelf --remove-rpath {} \;
+  fi
+fi
+
+# Product-template assets (optional): copy contents into the always-staged dir.
+if [ -d "${PRODUCT_DIR}/assets" ]; then
+  cp -R "${PRODUCT_DIR}/assets/." "${stage}/assets/"
+fi
+
+# Runtime images the default templates launch, stamped on as a label so a
+# golden-image bake can warm them with `docker inspect` + `docker pull` alone —
+# no daemon, no license. Derived from the rendered compose (scripts/runtime-images.ts),
+# never hardcoded. Products without that script simply don't carry the label.
+label_args=()
+if [ -f "${PRODUCT_DIR}/scripts/runtime-images.ts" ]; then
+  echo "==> resolving runtime images for the norsk-ctl.runtime-images label"
+  runtime_images="$(bun "${PRODUCT_DIR}/scripts/runtime-images.ts")"
+  label_args+=(--label "norsk-ctl.runtime-images=${runtime_images}")
+fi
+
+echo "==> docker build ${IMAGE_TAG}"
+docker build \
+  --build-arg BASE_IMAGE="${PRODUCT_BASE_IMAGE}" \
+  --build-arg BUN_IMAGE="$(product_bun_slim_image)" \
+  --build-arg PRODUCT_PORT="${PRODUCT_PORT}" \
+  "${label_args[@]}" \
+  -f "${driver_dir}/Dockerfile.bundle" -t "${IMAGE_TAG}" "${stage}"
+
+echo "==> built ${IMAGE_TAG}"

package/build/common.sh

@@ -0,0 +1,77 @@
+# Shared deployment constants + helpers for the product container images.
+# Single-sourced in @norskvideo/ctl-dev-kit and sourced by the product build
+# scripts (the bundle driver build-bundle-image.sh, and studio's bespoke
+# build-image.sh). This is the one place the pinned base + bun live, so no two
+# product images can drift.
+#
+# Location-independent: this file makes NO assumption about where in a repo it
+# sits (it used to live at products/deployment/common.sh and derive the repo
+# root from its own path). The same file works vendored/symlinked in the
+# monorepo and installed into a split-out product repo's node_modules — callers
+# pass the product directory in, they don't rely on this file's location.
+#
+# Base choice — gcr.io/distroless/cc-debian12: glibc plus libgcc/libstdc++ (bun
+# and probe's native rust addon link these) and nothing else — no shell, no
+# package manager. studio's compiled binary would fit the smaller
+# distroless/base-debian12, but we take probe's minimum (cc) for every product so
+# a host running several products pulls one shared base layer. Pinned by digest
+# because distroless publishes only moving tags (no immutable version tags). No
+# shell is fine: images run via exec-form CMD and health is checked over HTTP.
+PRODUCT_BASE_IMAGE="gcr.io/distroless/cc-debian12@sha256:7ee09f36862efbdbf70422db263e411c2618409ca46faa555bd5b636155307df"
+
+# The pinned bun version. Override with BUN_VERSION; otherwise walk up from the
+# given directory (default: PWD) to the nearest package.json declaring
+# "packageManager": "bun@X" — the workspace root in the monorepo, the repo root
+# in a split-out product. Prints X.
+product_bun_version() {
+  if [ -n "${BUN_VERSION:-}" ]; then
+    printf '%s' "${BUN_VERSION}"
+    return 0
+  fi
+  local dir version
+  dir="${1:-$PWD}"
+  while [ "${dir}" != "/" ]; do
+    if [ -f "${dir}/package.json" ]; then
+      version="$(sed -n 's/.*"packageManager": *"bun@\([^"]*\)".*/\1/p' "${dir}/package.json")"
+      if [ -n "${version}" ]; then
+        printf '%s' "${version}"
+        return 0
+      fi
+    fi
+    dir="$(dirname "${dir}")"
+  done
+  echo "could not determine bun version (no packageManager in any ancestor package.json)" >&2
+  return 1
+}
+
+# Prints the upstream oven/bun slim image ref for the pinned version. The bundle
+# products import their runtime bun from this image Docker-natively (COPY --from),
+# so they never touch the host cache; only studio's host-side --compile needs the
+# extracted binary below.
+product_bun_slim_image() {
+  local version
+  version="$(product_bun_version)" || return 1
+  printf 'oven/bun:%s-slim' "${version}"
+}
+
+# Prints the path to an upstream (glibc, FHS-loader) bun of the pinned version,
+# extracted from oven/bun:<version>-slim and cached. The nix-devshell bun is
+# patched to a /nix/store loader: it won't run in the base image, and baked into
+# a `--compile` binary it makes that binary fail to exec in a stock container.
+# So the bun that ships (bundle products) or does the compile (studio) must be
+# this one. Progress goes to stderr so `$(product_upstream_bun)` captures only
+# the path.
+product_upstream_bun() {
+  local version cache_dir bun_path cid
+  version="$(product_bun_version)" || return 1
+  cache_dir="${XDG_CACHE_HOME:-${HOME}/.cache}/norsk-ctl"
+  bun_path="${cache_dir}/bun-${version}"
+  if [ ! -x "${bun_path}" ]; then
+    echo "==> fetching upstream bun ${version} from oven/bun:${version}-slim" >&2
+    mkdir -p "${cache_dir}"
+    cid="$(docker create "oven/bun:${version}-slim")"
+    docker cp "${cid}:/usr/local/bin/bun" "${bun_path}"
+    docker rm "${cid}" >/dev/null
+  fi
+  printf '%s' "${bun_path}"
+}

package/conventions/CLAUDE.core.md

@@ -0,0 +1,49 @@
+<!-- BEGIN ctl-shared-conventions v1 -->
+<!--
+  This block is the SHARED conventions core, single-sourced in
+  @norskvideo/ctl-dev-kit (conventions/CLAUDE.core.md). It is copied verbatim
+  into each product repo's CLAUDE.md between these fenced markers, and a
+  drift-check gate (Workstream I) fails CI if a copy diverges from the dev-kit's
+  version. Do NOT hand-edit a copy — edit the dev-kit source and re-sync. The
+  per-product tail (this product's build, iterate loop, gotchas) lives OUTSIDE
+  the markers and is yours to own.
+
+  It is copied (not `@import`ed) on purpose: CLAUDE.md's value is being read
+  verbatim by a human on GitHub with no tooling, and an @import shows a human a
+  dead path.
+-->
+
+## Conventions (shared across all Norsk ctl product repos — do not edit in place)
+
+- **RED -> GREEN -> REFACTOR. No fix before its failing test.** Write the test,
+  run it, watch it fail against the old code, THEN write the fix. This applies
+  _most_ when the fix feels too obvious to bother — that's precisely when the
+  skip happens. If code somehow got written first: stash it, prove the test RED,
+  pop, prove GREEN.
+- **No `Co-Authored-By` tags on commits.** Imperative subject. Short body, only
+  if the why isn't obvious from the diff. Each commit logically scoped — don't
+  dump a phase into one commit.
+- **No emojis** in code, commits, or docs unless explicitly asked.
+- **Minimal comments.** Names explain _what_; comments explain _why_ —
+  non-obvious constraints, surprising invariants, workarounds for upstream bugs.
+  Don't restate the code.
+- **Result over throws** for predictable failures. `Result<T, E>` + `ok()`/
+  `err()`/`tryResult()` from `@norskvideo/ctl-foundation`. Throws are reserved
+  for genuine exceptions.
+- **ESLint / biome rules are non-negotiable** — adhere, never ignore. Keep the
+  whole project clean (`biome check .` exits 0), not just your own diff.
+- **Test temp dirs that get bind-mounted into a container must come from the
+  repo-local temp helper**, never `os.tmpdir()`/`/tmp`. On OrbStack, `/tmp` bind
+  mounts don't forward host->guest inotify events, so file watchers never fire —
+  a failure that looks exactly like a code bug. Unit tests that don't bind-mount
+  may keep using `os.tmpdir()`.
+- **Don't pipe test runs to `tail`** — you lose the failure context. Write output
+  to a temp file, then tail _that_ file for the results.
+- **Evolve the ctl<->product contract additively.** An older ctl must launch a
+  newer product release: never repurpose or remove a required launch-interface
+  field. When a product genuinely cannot launch on an older ctl it declares a
+  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.
+
+<!-- END ctl-shared-conventions v1 -->

package/local-dev/README.md

@@ -0,0 +1,45 @@
+# Local-dev overrides
+
+A product repo consumes ctl and the Norsk runtime as published packages/images.
+To develop a product against **un-published** ctl code or a **locally-built**
+media server, there are two independent override layers. Each is opt-in and
+leaves the default (registry/pinned) path untouched when unset.
+
+## 1. The npm layer — local `@norskvideo/ctl-*` checkouts
+
+The product depends on `@norskvideo/ctl-{sdk,foundation,product-template-schema,
+oas-to-ts,test-harness,commands,dev-kit}` at a caret range. To point one (or all)
+at a local checkout of the ctl monorepo instead of the registry, use
+`dev-link.sh`:
+
+```sh
+# link every @norskvideo/ctl-* dep to a sibling monorepo checkout
+node_modules/@norskvideo/ctl-dev-kit/local-dev/dev-link.sh ../norsk-ctl
+
+# undo — restore the registry versions
+node_modules/@norskvideo/ctl-dev-kit/local-dev/dev-link.sh --unlink
+```
+
+It `bun link`s the packages the monorepo exposes and re-installs; `--unlink`
+drops the overrides and reinstalls from the lockfile. Nothing is committed —
+the links live only in your local `node_modules`.
+
+## 2. The image layer — local media / studio image
+
+Every product's `shared/src/version.ts` already reads the runtime image tag from
+the environment, so this layer needs no script — just export the hook before you
+launch:
+
+- `NORSK_MEDIA_TAG` — override the Norsk media-server image tag.
+- `NORSK_STUDIO_TAG` — override the Norsk Studio image tag.
+
+Since Workstream C unified the tag convention, both are **bare tags** across every
+product (no full-ref/bare-tag divergence), so the same exported value means the
+same thing everywhere:
+
+```sh
+export NORSK_STUDIO_TAG=my-local-studio:dev
+bun run --cwd . iterate      # or the product's launch/iterate entry
+```
+
+Leave the hooks unset to launch the pinned tags the product declares.

package/local-dev/dev-link.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Point a product repo's @norskvideo/ctl-* dependencies at a local checkout of
+# the ctl monorepo (or restore the registry versions). See local-dev/README.md.
+#
+#   dev-link.sh <path-to-ctl-monorepo>   # link ctl-* packages to that checkout
+#   dev-link.sh --unlink                 # drop the overrides, reinstall pinned
+#
+# Nothing is committed — the links live only in this repo's node_modules.
+set -euo pipefail
+
+PACKAGES=(sdk foundation product-template-schema oas-to-ts test-harness commands dev-kit)
+product_root="$(cd "$(dirname "${BASH_SOURCE[0]}")" && git -C . rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+if [ "${1:-}" = "--unlink" ]; then
+  for pkg in "${PACKAGES[@]}"; do
+    bun unlink "@norskvideo/ctl-${pkg}" 2>/dev/null || true
+  done
+  echo "==> reinstalling pinned versions"
+  bun install --cwd "${product_root}"
+  echo "==> unlinked; registry versions restored"
+  exit 0
+fi
+
+mono="${1:?usage: dev-link.sh <path-to-ctl-monorepo> | --unlink}"
+mono="$(cd "${mono}" && pwd)"
+[ -d "${mono}/packages" ] || { echo "not a ctl monorepo checkout: ${mono}" >&2; exit 1; }
+
+for pkg in "${PACKAGES[@]}"; do
+  dir="${mono}/packages/${pkg}"
+  [ -d "${dir}" ] || { echo "  skip @norskvideo/ctl-${pkg} (not in checkout)"; continue; }
+  ( cd "${dir}" && bun link )
+  bun link "@norskvideo/ctl-${pkg}" --cwd "${product_root}"
+  echo "  linked @norskvideo/ctl-${pkg} -> ${dir}"
+done
+echo "==> linked against ${mono}; run dev-link.sh --unlink to restore"

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@norskvideo/ctl-dev-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}