@norskvideo/ctl-dev-kit 0.1.100 → 0.1.102

package/conventions/integration-testing.md

@@ -32,6 +32,28 @@ support code that hits a studio/media port must route through a `TEST_HOST`
 helper** (`process.env.NORSK_TEST_HOST ?? "localhost"`), never a hardcoded
 `localhost`. Daemon/backend fetches stay on `localhost`.
 
+### A studio host port binds loopback unless you ask otherwise
+
+norsk-ctl gives the **`studio`** service's compose ports (`STUDIO_HOST_PORT`) an
+explicit `127.0.0.1` bind at launch — docker publishes an unbound port on every
+interface and its rules sit ahead of ufw. No other service's ports are touched.
+
+A loopback bind is **unreachable via `host.docker.internal`**. So in the DooD
+runner, one of these must hold:
+
+- `NORSK_TEST_NET=direct` — the preferred answer, and what the canonical
+  `integration.yml` / `smoke.yml` / `build-docs.yml` topology step already sets.
+  Instances are reached by compose name on `norsk-net` at the **container** port,
+  so no host publish is involved at all.
+- the launch passes `--publish-debug-ports`, restoring the old binding. The
+  shared `runProductSmoke` and demo drivers do this for you when the host they
+  fetch from is not loopback, and only after probing that the resolved ctl
+  advertises the flag (the CLI is `.strict()`, and a product pins a released ctl
+  independently of the harness). A product's own launch code must do both.
+
+A harness reaching a studio port at `${NORSK_TEST_HOST}` while neither holds
+will see every studio gate time out with connection refused.
+
 ## Host-shared working directory (or studio EACCESes on boot)
 
 Studio bind-mounts its instance working directory as `${workdir}:/data` and runs

package/create-product/create-product.ts

@@ -10,7 +10,7 @@
 //     screen) added by FEATURE, not by a second copy of the skeleton.
 //
 // The convention layer is shared verbatim across every shape.
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { type Canon, loadAsset, loadCanon, PRODUCT_SENTINEL } from "./canon.ts";
 import { turnkey } from "./turnkey.ts";
@@ -101,13 +101,28 @@ const SHAPES: Record<ProductShape, ShapeModule> = {
   turnkey,
 };
 
-// Same known-good coherent set the dev-kit's own package.json pins. A fresh
-// repo's first upgrade-latest.yml run advances every one of these in lockstep.
-const DEFAULT_MEDIA_IMAGE = "norskvideo/norsk:1.2.1-2026-09-15-a41445b4";
+/** A pin from the dev-kit's own package.json — the coherent set set-sdk-source.ts
+ *  moves as one line, and the only copy that travels with the published package. */
+export function devKitPin(pkg: { devDependencies?: Record<string, string> }, name: string): string {
+  const pin = pkg.devDependencies?.[name];
+  if (pin === undefined) {
+    throw new Error(`the dev-kit's package.json pins no ${name}; a generated product would carry no version`);
+  }
+  return pin;
+}
+
+const devKitPackageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+  devDependencies?: Record<string, string>;
+};
+
+// Derived, never a second copy of the tag: a hardcoded default silently missed
+// every nightly sdk-bump, which moves the package.json line and nothing else.
+// Media's npm packages and image are built from one commit, so they share a tag.
+const DEFAULT_MEDIA_IMAGE = `norskvideo/norsk:${devKitPin(devKitPackageJson, "@norskvideo/norsk-sdk")}`;
+// Studio's npm packages and image ship from different commits, so its image tag
+// cannot be derived; it only has to sit on the lib pin's version line.
 const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.29.0-2026-09-10-dcf40e7c";
-// Studio's npm packages and image ship from different commits, so the default
-// lib pin can't be derived from the default image's tag.
-const DEFAULT_STUDIO_LIB = "1.29.0-2026-09-10-b21d9013";
+const DEFAULT_STUDIO_LIB = devKitPin(devKitPackageJson, "@norskvideo/norsk-studio");
 
 const bareTag = (ref: string) => ref.slice(ref.lastIndexOf(":") + 1);
 

package/doc-guide/instance-proxy.d.ts

@@ -17,7 +17,12 @@ export declare function startInstanceProxy(opts: {
      *  instead of `NORSK_TEST_HOST:studioHostPort` — a `noPublish` instance binds
      *  no host port, so the caller supplies its `norsk-net` reach
      *  (`<id>-studio-1:8000`) via `resolveEndpoint`. Omitted = today's
-     *  host-published behaviour. */
+     *  host-published behaviour.
+     *
+     *  Supply it whenever `NORSK_TEST_HOST` is not loopback: ctl binds a
+     *  product's STUDIO_HOST_PORT to `127.0.0.1`, which the host-gateway alias
+     *  cannot reach. The alternative is launching with `--publish-debug-ports`.
+     *  See conventions/integration-testing.md. */
     upstream?: {
         host: string;
         port: number;

package/package.json

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