@norskvideo/ctl-dev-kit 0.2.18 → 0.2.20

package/conventions/integration-testing.md

@@ -54,6 +54,42 @@ 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.
+- The names above carry the store dir as well as the port: two repos' slugs can
+  hash into the same port band, so a port-only name is not unique.
+- Still box-global and NOT namespaced: `norsk-net`, and a registered image
+  product's control-plane container NAME `norsk-product-<name>`. Its host port
+  is already docker-assigned (`127.0.0.1::4321`, read back by `docker inspect`);
+  older text here and in the reap steps that names a fixed 14321 is stale. Two
+  concurrent runs of the SAME product that both `product add --image` still
+  collide on the name.
+- Still banded, and still able to collide: the daemon's nginx proxy host port
+  (`daemon+3`), which is published on the host. Docker-assigned proxy ports are
+  in progress.
+
+## Reaching an image product's control plane
+
+`product add --image` loopback-publishes the control plane on a
+docker-assigned host port (`127.0.0.1::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 +161,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 +212,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/package.json

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