@norskvideo/ctl-dev-kit 0.1.2 → 0.1.4

package/build/flake.nix

@@ -3,12 +3,13 @@
 # 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.
 #
-# 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).
+# Three shells:
+#   nix develop         -> build tools (bun, cargo/rustc, git) + the pinned
+#   nix develop .#dev      `norsk-ctl` daemon on PATH. The everyday product dev
+#                          shell; the two are equivalent.
+#   nix develop .#build -> build tools only, no ctl. What CI (build-image /
+#                          integration) uses, so image builds never depend on the
+#                          ctl binary channel.
 #
 # `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
@@ -77,14 +78,19 @@
             pkgs.git
           ];
         in {
-          # CI (build-image) uses this — lean, no ctl fetch.
+          # Everyday dev shell — build tools + the pinned norsk-ctl daemon.
+          # `nix develop` and `nix develop .#dev` are equivalent.
           default = pkgs.mkShell {
-            buildInputs = buildTools;
+            buildInputs = buildTools ++ [ (mkCtl system) ];
           };
-          # Local product dev loop — build tools + the pinned daemon on PATH.
           dev = pkgs.mkShell {
             buildInputs = buildTools ++ [ (mkCtl system) ];
           };
+          # Lean shell for CI (build-image / integration) — no ctl fetch, so
+          # image builds never depend on the ctl binary channel.
+          build = pkgs.mkShell {
+            buildInputs = buildTools;
+          };
         });
     };
 }

package/local-dev/README.md

@@ -13,8 +13,9 @@ dependency; it is the released binary, pinned by version+hash in the repo's
 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)
+nix develop              # build tools (bun, cargo/rustc, git) + the pinned norsk-ctl
+#   nix develop .#dev    # equivalent alias
+#   nix develop .#build  # lean shell, no ctl — what CI (build-image/integration) uses
 
 norsk-ctl serve          # daemon on :8333, oauth2 proxy on :9443
 norsk-ctl --version      # confirm the pinned build
@@ -54,8 +55,9 @@ HARDWARE=none NORSK_LICENSE_FILE=... bun run iterate           # no GPU reservat
 # Advanced overrides
 
 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
 
@@ -95,3 +97,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. Use
+`nix develop .#build` on the product side so the flake's pinned `norsk-ctl`
+doesn't shadow the one you're running from source.
+
+```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.2",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     "./package.json": "./package.json"