@norskvideo/ctl-dev-kit 0.1.105 → 0.2.1

package/conventions/CLAUDE.core.md

@@ -102,14 +102,16 @@
   accidental regressions to the things that matter most.
 - **Know who reads it — name the persona before writing docs or a
   persona-facing surface.** Every Norsk ctl product writes for the same four
-  reader personas — Evaluator, Builder, Integrator, Operator (SRE) — defined in
-  `@norskvideo/ctl-dev-kit/conventions/personas.md`, with this product's own
-  audiences mapped onto them in its `docs/personas.md`. Before writing or
-  restructuring docs, a configure/dashboard surface, onboarding material, or any
-  copy a persona will read, name that reader and honour the ownership handoff
-  (Evaluator/Builder -> product repo, Operator -> ctl, Integrator -> both).
-  Runtime actors (the roles people play in the deployed product) are NOT
-  doc-reader personas: the operator who runs it is the Builder; guests who are
-  invited in receive onboarding kit, they don't read the manual.
+  reader personas — Evaluator, Builder, Integrator, Administrator (SRE) —
+  defined in `@norskvideo/ctl-dev-kit/conventions/personas.md`, with this
+  product's own audiences mapped onto them in its `docs/personas.md`. Before
+  writing or restructuring docs, a configure/dashboard surface, onboarding
+  material, or any copy a persona will read, name that reader and honour the
+  ownership handoff (Evaluator/Builder -> product repo, Administrator -> ctl,
+  Integrator -> both). Runtime actors (the roles people play in the deployed
+  product) are NOT doc-reader personas, and neither are norsk-ctl's access
+  roles, whose names collide with two of these by coincidence: whoever stands
+  the deployment up and runs it reads as the Builder; guests who are invited in receive
+  onboarding kit, they don't read the manual.
 
 <!-- END ctl-shared-conventions v1 -->

package/conventions/docs.md

@@ -39,9 +39,10 @@ Name the reader before writing a page (see `personas.md` and the product's own
 - **Builder** — the illustrated task pages. The domain-fluent operator who stands
   the show up and runs it.
 
-Integrator and Operator are served elsewhere (reference / ctl). Runtime actors
-(a commentator, a contributor, a producer) are NOT readers of the manual — the
-operator is the Builder; the others receive join links and onboarding kit.
+Integrator and Administrator are served elsewhere (reference / ctl). Runtime
+actors (a commentator, a contributor, a producer) are NOT readers of the
+manual — whoever runs the show reads as the Builder; the others receive join
+links and onboarding kit.
 
 ## Voice
 

package/conventions/personas.md

@@ -4,7 +4,7 @@ The shared reader vocabulary. Every Norsk ctl product — probe, commentary,
 playout, the turnkeys — writes docs for the same four personas, so a reader who
 learns one product's docs knows how to navigate the next. Read this before
 writing or restructuring a product's `docs/`; then keep the product's own
-`docs/personas.md`, which maps *this* product's named audiences and runtime
+`docs/personas.md`, which maps _this_ product's named audiences and runtime
 roles onto the four below.
 
 This is a **shipped reference**, not a drift-gated copy: you consume it from
@@ -36,12 +36,12 @@ founder — or a **sales engineer demoing it on their behalf**. Wants to know
 
 ### 2. Builder
 
-Building or standing up a real deployment *with* the product. A developer or a
+Building or standing up a real deployment _with_ the product. A developer or a
 technical producer/operator. Wants it to work; does not want to become a DevOps
 expert, and does not want to hand-write config/graph YAML.
 
 - **Skills**: can run commands, knows what a container is. May be deeply fluent
-  in the product's *domain* (broadcast transports, say) while still not wanting
+  in the product's _domain_ (broadcast transports, say) while still not wanting
   ctl/Docker internals — a product refines this in its own mapping.
 - **Wants**: task-oriented hand-holding; a UI that exposes everything; good
   errors with fix hints; sensible defaults.
@@ -51,7 +51,7 @@ expert, and does not want to hand-write config/graph YAML.
   gives up.
 - **Usually the most underserved persona**, and usually the product's sweet
   spot — the Integrator has generated reference, the Evaluator has zero-to-hero,
-  the Operator is largely ctl's; the Builder's task guides are the product's own
+  the Administrator is largely ctl's; the Builder's task guides are the product's own
   work and the thing most worth investing in.
 
 ### 3. Integrator
@@ -67,7 +67,7 @@ launches, CI/CD, programmatic control.
 - **Failure mode**: the reference has drifted from the tool; trust is lost; they
   read the source instead.
 
-### 4. Operator (SRE)
+### 4. Administrator (SRE)
 
 Running the product in production. Responsible for uptime, cost, security.
 
@@ -91,12 +91,12 @@ no marketing copy. Don't build a separate doc track for it.
 The persona a page serves decides which repo owns it, once products are split
 out of ctl:
 
-| Persona    | Owner repo    |
-| ---------- | ------------- |
-| Evaluator  | **product**   |
-| Builder    | **product**   |
-| Integrator | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
-| Operator   | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's |
+| Persona       | Owner repo                                                                                                               |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Evaluator     | **product**                                                                                                              |
+| Builder       | **product**                                                                                                              |
+| Integrator    | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
+| Administrator | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's                         |
 
 The test: **if the answer changes when you swap products, it's product docs; if
 it changes when you upgrade ctl, it's ctl docs.** Ownership is not presentation —
@@ -107,17 +107,23 @@ a single rendered site can still interleave both (see norsk-ctl's
 
 A deployed product has **runtime actors** — the roles people play in the running
 system (an operator at a console, a guest who joins, an analyst who reads a
-report). These are *not* a fifth, sixth, seventh persona, and indexing docs by
+report). These are _not_ a fifth, sixth, seventh persona, and indexing docs by
 them is the most common way a product's docs sprawl.
 
 Reconcile them like this:
 
 - The actor who **sets the deployment up and runs it** is the **Builder** (and,
-  live, the Operator in the ctl sense) — the same human, wearing hats. Their
-  material is the Builder task guides.
+  live, the Administrator in the ctl sense) — the same human, wearing hats.
+  Their material is the Builder task guides. Neither hat is an **access role**:
+  norsk-ctl's platform roles (RFC 0003 §2.6, ADR-0013) say what a signed-in
+  principal may _do_, and two of their names collide with persona names —
+  Builder/`builder` and Administrator/`admin` — by coincidence, not by design.
+  A persona is who you write for; a role is what an enforcement point checks.
+  The roles are not listed here: this file ships to every product repo with no
+  gate tying it to the ladder, so a copy of the list would rot unnoticed.
 - Actors who are **invited into** the running deployment (a guest, a
   contributor) rarely read the manual at all — they receive a link, and maybe an
-  onboarding message. Material authored *for* them but *handed out by* the
+  onboarding message. Material authored _for_ them but _handed out by_ the
   Builder — join-page guides, onboarding email templates — is **distribution /
   onboarding kit**, indexed separately from the Builder's own task guides, not
   as manual chapters.

package/create-product/turnkey.ts

@@ -311,7 +311,7 @@ function rootPackageJson(ctx: ShapeContext): string {
       },
       devDependencies: {
         "@biomejs/biome": "2.5.5",
-        "@norskvideo/ctl-dev-kit": "^0.1.10",
+        "@norskvideo/ctl-dev-kit": "^0.2.0",
         // The demo driver (`ctl-demo`, tests/demo.spec.ts) — hoisted here so the
         // root `demo` script resolves the bin.
         "@norskvideo/ctl-test-harness": "^0.1.23",
@@ -1571,7 +1571,7 @@ function testsPackageJson(ctx: ShapeContext): string {
       private: true,
       type: "module",
       devDependencies: {
-        "@norskvideo/ctl-dev-kit": "^0.1.10",
+        "@norskvideo/ctl-dev-kit": "^0.2.0",
         // Same range the backend declares: the tests tree imports the schema
         // directly, and bun links a member's deps into its OWN node_modules —
         // the backend's copy is not reachable from here.

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

@@ -6,12 +6,12 @@ export interface InstanceProxy {
     stop: () => void;
 }
 /** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
- *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
- *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
- *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
+ *  studioHostPort, where `prefix` is the `studioUrlPrefix` Studio advertises.
+ *  `dashboardKey` is the product's baked dashboard path segment (the dashboard
+ *  is served at `/dashboard/<dashboardKey>/`) and so also names the `env`
+ *  document the prefix is read from. */
 export declare function startInstanceProxy(opts: {
     studioHostPort: number;
-    instanceId: string;
     dashboardKey: string;
     /** Explicit upstream studio endpoint. When set, the proxy forwards here
      *  instead of `NORSK_TEST_HOST:studioHostPort` — a `noPublish` instance binds
@@ -27,4 +27,4 @@ export declare function startInstanceProxy(opts: {
         host: string;
         port: number;
     };
-}): InstanceProxy;
+}): Promise<InstanceProxy>;

package/doc-guide/instance-proxy.js

@@ -2,10 +2,10 @@
 //
 // A product's baked operator dashboard is built to run behind the runner's oauth2
 // proxy: its `env` endpoint advertises instance-scoped paths
-// (`apiBasePath: /instance/<id>/live/api`, `wsBasePath: /instance/<id>/live`).
+// (`apiBasePath: /instance/<id>/studio/live/api`, `wsBasePath: …/studio/live`).
 // The harness, though, publishes Studio DIRECTLY on studioHostPort with no
-// `/instance/<id>` prefix — so those advertised paths 404 and the console never
-// leaves its "workflow starting up" splash.
+// prefix at all — so those advertised paths 404 and the console never leaves
+// its "workflow starting up" splash.
 //
 // Rather than drag the whole oauth2 proxy + TLS + port 443 into a doc run, this
 // serves the dashboard under exactly the prefix `env` advertises and strips it
@@ -15,12 +15,48 @@
 // Response headers that describe the upstream transfer encoding; fetch() has
 // already decoded the body, so forwarding these would misdescribe what we send.
 const STRIP_RESPONSE_HEADERS = ["content-encoding", "content-length", "transfer-encoding"];
+// Studio is long up by the time a guide starts its proxy (the guide has already
+// waited on streams), so this window only covers a slow first byte — it is not
+// a readiness wait.
+const ENV_DISCOVERY_TIMEOUT_MS = 10_000;
+const ENV_DISCOVERY_INTERVAL_MS = 250;
+/** The prefix ctl told Studio to emit its own absolute paths under. Never
+ *  reconstruct it: ctl anchors it on the studio ROUTE
+ *  (`/instance/<id>/studio`), deliberately leaving the `/instance/<id>/`
+ *  catch-all free for a product's sidecar UI, and that choice is ctl's to
+ *  change. Studio hands it back verbatim on the `env` document it serves beside
+ *  every dashboard, which is the same document the dashboard itself trusts. */
+async function discoverStudioUrlPrefix(httpUpstream, dashboardKey) {
+    const url = `${httpUpstream}/dashboard/${dashboardKey}/env`;
+    const deadline = Date.now() + ENV_DISCOVERY_TIMEOUT_MS;
+    let lastFailure = "never reached";
+    for (;;) {
+        const res = await fetch(url).catch((e) => {
+            lastFailure = `fetch failed: ${String(e)}`;
+            return null;
+        });
+        if (res?.ok) {
+            const body = (await res.json().catch(() => null));
+            const prefix = body?.studioUrlPrefix;
+            // A prefix-less studio (bare `bun run dev`) advertises "", which is a
+            // legitimate answer: serve at the proxy root and strip nothing.
+            if (typeof prefix === "string")
+                return prefix;
+            throw new Error(`${url} is not a studio env document (no studioUrlPrefix)`);
+        }
+        if (res)
+            lastFailure = `HTTP ${res.status}`;
+        if (Date.now() >= deadline)
+            throw new Error(`could not read the advertised prefix from ${url} (${lastFailure})`);
+        await Bun.sleep(ENV_DISCOVERY_INTERVAL_MS);
+    }
+}
 /** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
- *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
- *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
- *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
-export function startInstanceProxy(opts) {
-    const prefix = `/instance/${opts.instanceId}`;
+ *  studioHostPort, where `prefix` is the `studioUrlPrefix` Studio advertises.
+ *  `dashboardKey` is the product's baked dashboard path segment (the dashboard
+ *  is served at `/dashboard/<dashboardKey>/`) and so also names the `env`
+ *  document the prefix is read from. */
+export async function startInstanceProxy(opts) {
     // Studio's published port is on localhost for a local run, but in the
     // docker-outside-of-docker CI the test process runs in a container and the
     // port lives on the host gateway — reach it via NORSK_TEST_HOST
@@ -31,7 +67,14 @@ export function startInstanceProxy(opts) {
     const upstreamHost = opts.upstream?.host ?? process.env.NORSK_TEST_HOST ?? "localhost";
     const upstreamPort = opts.upstream?.port ?? opts.studioHostPort;
     const httpUpstream = `http://${upstreamHost}:${upstreamPort}`;
-    const strip = (pathname) => pathname === prefix ? "/" : pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
+    const prefix = await discoverStudioUrlPrefix(httpUpstream, opts.dashboardKey);
+    // An empty prefix (a studio with no studio_url_prefix) makes every path its
+    // own strip result, which the startsWith arm already gives.
+    const strip = (pathname) => {
+        if (prefix !== "" && pathname === prefix)
+            return "/";
+        return pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
+    };
     const server = Bun.serve({
         port: 0,
         async fetch(req, srv) {

package/package.json

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