@norskvideo/ctl-dev-kit 0.1.1 → 0.1.3

package/build/flake.nix

@@ -1,14 +1,21 @@
-# Product build shell — single-sourced in @norskvideo/ctl-dev-kit and copied
-# verbatim into each split product repo (nix needs a flake.nix at the repo root
-# for `nix develop`; it can't pull one from an npm package at CI bootstrap). The
-# copy is drift-gated (Workstream I), same model as the fenced CLAUDE.md core.
+# Product build + dev shell — single-sourced in @norskvideo/ctl-dev-kit and
+# copied verbatim into each split product repo (nix needs a flake.nix at the repo
+# root for `nix develop`; it can't pull one from an npm package at CI bootstrap).
+# The copy is drift-gated (Workstream I), same model as the fenced CLAUDE.md core.
 #
-# Trimmed to what a product image build needs: bun (all products), cargo + rustc
-# (probe's native signer addon), git. docker is provided by the CI runner, not
-# nix. The nixpkgs pin (and flake.lock beside this file) match the monorepo's, so
-# every product resolves the identical bun 1.3.13 the workspace pins.
+# Two shells:
+#   nix develop        -> build tools only (bun, cargo/rustc, git). This is what
+#                         CI (build-image) uses; it must stay lean and must NOT
+#                         depend on fetching the ctl binary.
+#   nix develop .#dev  -> the above PLUS the pinned `norsk-ctl` daemon on PATH,
+#                         for the local product dev loop (serve + product add).
+#
+# `norsk-ctl` is the released daemon binary pulled from the S3 channel and pinned
+# by version+hash (reproducible). It is NOT built from source here — a product
+# dev consumes the shipped ctl exactly as a customer does. Bump with:
+#   packages/dev-kit/build/refresh-ctl-pin.sh        (writes ctlVersion + hashes)
 {
-  description = "norsk-ctl product build shell";
+  description = "norsk-ctl product build + dev shell";
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/d233902339c02a9c334e7e593de68855ad26c4cb"; # nixpkgs-unstable 2026-05-15, bun 1.3.13
@@ -18,17 +25,65 @@
     let
       systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
       forAllSystems = f: builtins.listToAttrs (map (s: { name = s; value = f s; }) systems);
+
+      # --- norsk-ctl channel pin -------------------------------------------
+      # The released daemon, one build per platform. Bump these together.
+      ctlVersion = "0.1.0-2026-07-27-3165484";
+      ctlBase = "https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl";
+      ctlAsset = {
+        "x86_64-linux"   = { plat = "linux-x64";    hash = "sha256-11vl/SsWlQnxt+yNl9lCcbOI/uJh1fcbKKnHSYHt2PY="; };
+        "aarch64-linux"  = { plat = "linux-arm64";  hash = "sha256-AhrpIdXsw6cTzobfECfirKAIDnx01k0PQeylTfwIUJg="; };
+        "aarch64-darwin" = { plat = "darwin-arm64"; hash = "sha256-l17fqyicZa3SZLkmUpisZIJ3xWf94JOeuXDZrpoRGic="; };
+        "x86_64-darwin"  = { plat = "darwin-x64";   hash = "sha256-wYEKu0ITDpBONMnig4aqzEQ1ZgPG17JnhJZoGiA5MKc="; };
+      };
+
+      mkCtl = system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          asset = ctlAsset.${system};
+        in
+        pkgs.stdenv.mkDerivation {
+          pname = "norsk-ctl";
+          version = ctlVersion;
+          src = pkgs.fetchurl {
+            url = "${ctlBase}/${ctlVersion}/norsk-ctl-${ctlVersion}-${asset.plat}";
+            hash = asset.hash;
+          };
+          dontUnpack = true;
+          # bun single-file executables embed a trailing payload; stripping
+          # corrupts them, and on Linux the raw binary needs its interpreter +
+          # libstdc++ rpath patched to the nix store.
+          dontStrip = true;
+          nativeBuildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.autoPatchelfHook ];
+          buildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.stdenv.cc.cc.lib ];
+          installPhase = ''
+            runHook preInstall
+            install -Dm755 "$src" "$out/bin/norsk-ctl"
+            runHook postInstall
+          '';
+        };
     in {
+      packages = forAllSystems (system: {
+        norsk-ctl = mkCtl system;
+      });
+
       devShells = forAllSystems (system:
-        let pkgs = import nixpkgs { inherit system; };
+        let
+          pkgs = import nixpkgs { inherit system; };
+          buildTools = [
+            pkgs.bun
+            pkgs.cargo # builds the native product-signer addon (probe/native)
+            pkgs.rustc
+            pkgs.git
+          ];
         in {
+          # CI (build-image) uses this — lean, no ctl fetch.
           default = pkgs.mkShell {
-            buildInputs = [
-              pkgs.bun
-              pkgs.cargo # builds the native product-signer addon (probe/native)
-              pkgs.rustc
-              pkgs.git
-            ];
+            buildInputs = buildTools;
+          };
+          # Local product dev loop — build tools + the pinned daemon on PATH.
+          dev = pkgs.mkShell {
+            buildInputs = buildTools ++ [ (mkCtl system) ];
           };
         });
     };

package/build/refresh-ctl-pin.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Repin the norsk-ctl daemon in flake.nix to a channel version. Resolves the
+# version (default: the `latest` channel), fetches each platform's sha256
+# sidecar, converts to SRI, and rewrites `ctlVersion` + the four `hash =` lines
+# in flake.nix in place. Run from anywhere; targets the flake.nix beside it.
+#
+#   refresh-ctl-pin.sh                       # pin to the current `latest`
+#   refresh-ctl-pin.sh 0.1.0-2026-07-27-...  # pin to an explicit version
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+flake="$here/flake.nix"
+base="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+
+ver="${1:-$(curl -fsSL "$base/latest")}"
+echo "pinning norsk-ctl -> $ver"
+
+declare -A plat=(
+  [x86_64-linux]=linux-x64
+  [aarch64-linux]=linux-arm64
+  [aarch64-darwin]=darwin-arm64
+  [x86_64-darwin]=darwin-x64
+)
+
+# nix keys the ctlAsset attrset by system; rewrite each system's hash line. The
+# hash lines live in the `ctlAsset = { ... }` block, one per platform string.
+for sys in "${!plat[@]}"; do
+  p="${plat[$sys]}"
+  hex="$(curl -fsSL "$base/$ver/norsk-ctl-$ver-$p.sha256" | awk '{print $1}')"
+  [ -n "$hex" ] || { echo "no sha256 sidecar for $p" >&2; exit 1; }
+  sri="$(nix hash convert --hash-algo sha256 --to sri "$hex")"
+  # Replace the hash on the line that mentions this platform's plat string.
+  perl -0pi -e "s{(plat = \"$p\";\\s*hash = \")[^\"]*(\")}{\${1}$sri\${2}}" "$flake"
+  echo "  $sys ($p): $sri"
+done
+
+perl -0pi -e "s{(ctlVersion = \")[^\"]*(\")}{\${1}$ver\${2}}" "$flake"
+echo "updated $flake"
+echo "next: copy this flake.nix into each split product repo root (or re-run the split)"

package/local-dev/README.md

@@ -1,9 +1,62 @@
-# Local-dev overrides
+# Developing a split product repo
+
+A product repo (funke-pegasus, playout, probe, commentary, studio) is
+self-contained: it consumes ctl and the Norsk runtime as **published
+packages/images**, and needs no norsk-ctl source checkout to build, launch, or
+test. This is the whole point of the split — you clone the product and go.
+
+## Running ctl — the daemon
+
+`norsk-ctl` (the daemon + CLI that launches product instances) is **not** an npm
+dependency; it is the released binary, pinned by version+hash in the repo's
+`flake.nix` (single-sourced from `@norskvideo/ctl-dev-kit`). The dev shell puts
+it on `PATH`:
+
+```sh
+nix develop .#dev        # build tools (bun, cargo/rustc, git) + the pinned norsk-ctl
+#   nix develop          # build-only shell — no ctl (this is what CI build-image uses)
+
+norsk-ctl serve          # daemon on :8333, oauth2 proxy on :9443
+norsk-ctl --version      # confirm the pinned build
+```
+
+The binary is fetched from the S3 channel and patched for the local system
+(`autoPatchelfHook` on Linux/NixOS, plain install on macOS). To move the pin,
+bump `ctlVersion` + the four platform hashes in `flake.nix` (or run
+`packages/dev-kit/build/refresh-ctl-pin.sh` in the monorepo).
+
+## The two dev loops
+
+**Inner loop (fast, no image build)** — run the backend from source and register
+it as a `kind: dev` product, so edits to the backend / workflow / components land
+without building a container:
+
+```sh
+bun install
+bun run dev                                             # backend + frontend (Vite)
+norsk-ctl product add --dev-url http://localhost:<backendPort>
+norsk-ctl instance launch-template <id> --template <t> --hardware none
+```
+
+**Outer loop (real container)** — rebuild the product image and reload it into
+the live daemon, with pin + segfault guards. This is `deployment/iterate.sh`:
+
+```sh
+NORSK_LICENSE_FILE=/path/to/license.json bun run iterate       # needs a running daemon + GPU
+HARDWARE=none NORSK_LICENSE_FILE=... bun run iterate           # no GPU reservation
+```
+
+`test:integration` uses the same daemon path but against the **released** ctl
+(via `NORSK_CTL_BINARY`), exactly as CI does — see `.github/workflows/integration.yml`.
+
+---
+
+# Advanced 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.
+media server, there are three independent override layers. Each is opt-in and
+leaves the default (registry/pinned) path untouched when unset. They compose:
+changing the daemon *and* a ctl library it exposes means layers 1 + 3 together.
 
 ## 1. The npm layer — local `@norskvideo/ctl-*` checkouts
 
@@ -43,3 +96,45 @@ bun run --cwd . iterate      # or the product's launch/iterate entry
 ```
 
 Leave the hooks unset to launch the pinned tags the product declares.
+
+## 3. The daemon layer — run ctl from a source checkout (`../norsk-ctl`)
+
+Use this when you are changing the **daemon itself** (packages/norsk-ctl) and
+want the product to launch through your build instead of the pinned binary. The
+daemon is a single process on `:8333` — where you start it from is irrelevant, so
+just run it out of your checkout and drive it with the same checkout's CLI. Skip
+`nix develop .#dev` (its pinned `norsk-ctl` would shadow yours); the plain
+`nix develop` shell is enough on the product side.
+
+```sh
+# 1. daemon, from your ctl checkout (root `cli` script -> packages/norsk-ctl cli)
+( cd ../norsk-ctl && bun run cli serve )
+
+# 2. product backend, from the product repo
+bun run dev
+
+# 3. register + launch, using the SOURCE cli against the SOURCE daemon
+bun run --cwd ../norsk-ctl cli product add --dev-url http://localhost:<backendPort>
+bun run --cwd ../norsk-ctl cli instance launch-template demo --template <t> --hardware none
+```
+
+No linking is needed for this — you are running the daemon *code* directly. Pair
+with layer 1 (`dev-link.sh`) only if you also changed a `@norskvideo/ctl-*`
+library the product *compiles* against.
+
+### Integration tests against source ctl
+
+The harness spawns the daemon from `NORSK_CTL_BINARY` as `<that> serve …`. A split
+repo has no in-workspace ctl source for it to auto-discover, so point that env at
+a one-line wrapper that forwards to your checkout's CLI:
+
+```sh
+printf '#!/usr/bin/env bash\nexec bun run --cwd %s cli "$@"\n' "$(cd ../norsk-ctl && pwd)" > /tmp/norsk-ctl-src
+chmod +x /tmp/norsk-ctl-src
+NORSK_CTL_BINARY=/tmp/norsk-ctl-src NORSK_LICENSE_FILE=/path/to/license.json bun run test:integration
+```
+
+The wrapper forwards `serve` / `product add` / everything, so the whole slow tier
+runs against `../norsk-ctl`. (`NORSK_CTL_BINARY` resolution lives in
+`@norskvideo/ctl-test-harness`'s `cli-command.ts`: explicit path → in-workspace
+source → `norsk-ctl` on PATH.)

package/package.json

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