@norskvideo/ctl-dev-kit 0.2.17 → 0.2.19

package/conventions/integration-testing.md

@@ -54,6 +54,35 @@ runner, one of these must hold:
 A harness reaching a studio port at `${NORSK_TEST_HOST}` while neither holds
 will see every studio gate time out with connection refused.
 
+## The host docker daemon is shared between jobs
+
+The x64 runners are sibling containers on ONE host docker daemon, so anything
+named globally is shared by every concurrent job, whichever repo it belongs to.
+On 2026-10-02 a reuters tier and a commentary tier each `compose up`ed
+`norsk-proxy` over the other's, and reuters' teardown removed it mid-test.
+
+- `startDaemon` (and so every harness built on it) names the daemon's proxy and
+  cpu-monitor sidecar after its port (`norsk-proxy-<port>`,
+  `norsk-ctl-cpu-monitor-<port>`). Don't override them back to the defaults.
+- An image your suite builds must carry a **per-run tag** (e.g.
+  `<repo>:ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT`), not `:dev` — a concurrent run
+  can replace a fixed tag between your build and your `product add`. `docker rmi`
+  it at teardown, or the host fills up.
+- Still box-global and NOT namespaced: `norsk-net`, and a registered image
+  product's control plane `norsk-product-<name>` on `127.0.0.1:14321`. Two
+  concurrent runs of the SAME product that both `product add --image` will
+  collide there.
+
+## Reaching an image product's control plane
+
+`product add --image` loopback-publishes the control plane
+(`127.0.0.1:<port>:4321`). On a DooD runner that loopback is the HOST's, so a
+test that probes `localhost:<published port>` reaches nothing. With
+`NORSK_TEST_NET=direct`, dial the container's own address
+(`docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}'`)
+on 4321 — the same thing the daemon does under
+`NORSK_CTL_PRODUCT_REACH=container-address`.
+
 ## Host-shared working directory (or studio EACCESes on boot)
 
 Studio bind-mounts its instance working directory as `${workdir}:/data` and runs
@@ -125,10 +154,11 @@ runs. Add `bun run build:image` inside the `nix develop .#build` block (docker i
 reachable there); it also builds the dist the dev backend serves `/configure`
 from.
 
-## Stale node_modules on `clean: false` runners
+## Stale node_modules on reused workspaces
 
-The runners check out `clean: false` (to preserve `test-temp/`), so
-`node_modules` **persists between runs**, and `bun install --frozen-lockfile`
+The convention workflows now check out `clean: true` with test-temp routed to
+`$RUNNER_TEMP`, but a hand-owned workflow on `clean: false` keeps
+`node_modules` **between runs**, and `bun install --frozen-lockfile`
 does **not** reliably relink a workspace-hoisted package whose version moved. A
 stale `@norskvideo/ctl-test-harness@0.1.2` once survived a bump to `0.1.3`, so a
 newly-added export was `SyntaxError: export 'X' not found` and the suite crashed
@@ -175,6 +205,12 @@ three optional hooks the workflow calls if they are executable:
 | `scripts/integration/prepare.sh`       | before `bun run test:integration` | builds the suite needs on disk — a frontend dist the daemon fetches, an image it launches |
 | `scripts/integration/verify.sh`        | after the suite                   | post-suite checks; absent, a repo with `tests/demo.spec.ts` gets `bun run demo -- check`  |
 
+The hooks run in the **same workflow step** as the suite, so a hook that writes
+to `$GITHUB_ENV` changes nothing the suite sees — GitHub applies that file only
+to later steps. Commentary's enforced-path opt-out was dead for its whole life
+that way. Hand the suite a value by having both sides derive it (a tiny script
+the hook runs and the test imports), not through `$GITHUB_ENV`.
+
 `bun run test:integration` is the product's claim of what its tier is, and
 ctl's release gate believes it: a `ctl-candidate` dispatch runs this workflow
 and the reported result decides whether `latest` moves.

package/conventions/integration.yml

@@ -178,6 +178,39 @@ jobs:
             echo "NORSK_RUNNER_OWNS_DOCKER=true" >> "$GITHUB_ENV"
           fi
 
+      # Integration needs this host's docker to be able to create a network: the
+      # harness makes norsk-net and a network per instance. On 2026-10-02
+      # ashton-nuc's filter table had lost DOCKER-ISOLATION-STAGE-2, so every
+      # create failed with "Chain 'DOCKER-ISOLATION-STAGE-2' does not exist" --
+      # and commentary, probe and playout each ran a FULL integration suite on it
+      # and reported the result as test failures, 18 and 72 chain errors deep in
+      # their logs. The same host took four of that night's norsk image jobs down
+      # the same way. Nothing said "this machine's docker is broken".
+      #
+      # The chain is not readable without root on these runners, so this asserts
+      # the capability instead: create a throwaway network, remove it. One step,
+      # its own name, so the jobs API attributes the failure to it rather than to
+      # whatever composite step happened to be running.
+      - name: Check this host's docker can still create a network
+        run: |
+          set -uo pipefail
+          net="preflight-${{ github.run_id }}-${{ github.run_attempt }}-$RANDOM"
+          if err=$(docker network create "$net" 2>&1); then
+            docker network rm "$net" >/dev/null 2>&1 || true
+            echo "docker can create networks on $(hostname) -- ok"
+            exit 0
+          fi
+          echo "::error::docker on this runner cannot create a network, so every container this suite starts would silently not exist -- the tests would fail for a reason that is not theirs. Host: $(hostname). Fix: \`sudo systemctl restart docker\` on that machine (it rebuilds the DOCKER/DOCKER-ISOLATION iptables chains), then re-run."
+          echo "$err"
+          echo "--- docker0 (a subnet other than 172.17.0.1/16 means it was re-addressed) ---"
+          ip -br addr show docker0 2>/dev/null || true
+          echo "--- networks and their subnets ---"
+          for n in $(docker network ls --format '{{.Name}}' 2>/dev/null); do
+            printf '%-28s ' "$n"
+            docker network inspect "$n" --format '{{range .IPAM.Config}}{{.Subnet}} {{end}}' 2>/dev/null || echo
+          done
+          exit 1
+
       # `product add --image` publishes the control plane on 127.0.0.1:14321. The
       # daemon means to reap it on shutdown (daemon.ts, model B) but only does so
       # gracefully, and this workflow cancels its own superseded runs -- a killed

package/package.json

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