@norskvideo/ctl-dev-kit 0.2.77 → 0.2.79

package/create-product/features/dashboard.ts

@@ -13,6 +13,7 @@
 // directory below is not a free choice.
 import type { GeneratedFile, ShapeContext } from "../create-product.ts";
 import { EXAMPLE_ID } from "./components.ts";
+import { TEST_SETUP_TS, UI_TEST_DEV_DEPENDENCIES, VITEST_CONFIG_TS } from "./ui-tests.ts";
 
 /** The tar ships workflow.yml at its root, so Studio knows the workflow by this name. */
 export const WORKFLOW_NAME = "workflow";
@@ -39,6 +40,7 @@ function packageJson(ctx: ShapeContext): string {
         dev: "bunx vite build --watch",
         clean: `rm -rf ../dashboards/${WORKFLOW_NAME}`,
         typecheck: "bunx tsc --noEmit",
+        test: "vitest run",
       },
       dependencies: {
         react: "^19.0.0",
@@ -51,6 +53,7 @@ function packageJson(ctx: ShapeContext): string {
         "@vitejs/plugin-react": "^6.0.1",
         typescript: "^5.7.2",
         vite: "^8.0.0",
+        ...UI_TEST_DEV_DEPENDENCIES,
       },
     },
     null,
@@ -209,6 +212,38 @@ export default function App({ env }: { env: Env }) {
 }
 `;
 
+// A stand-in for the component's state socket: what a dashboard test drives
+// instead of a running Studio.
+const APP_TEST_TSX = `import { act, render, screen } from "@testing-library/react";
+import { afterEach, expect, test, vi } from "vitest";
+import App from "./App.tsx";
+
+class FakeSocket {
+  static last: FakeSocket | undefined;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  constructor(readonly url: string) {
+    FakeSocket.last = this;
+  }
+  close() {}
+  deliver(message: unknown) {
+    this.onmessage?.({ data: JSON.stringify(message) });
+  }
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test("shows the component's state as it arrives", () => {
+  vi.stubGlobal("WebSocket", FakeSocket);
+  render(<App env={{ apiBasePath: "/api", wsBasePath: "/ws" }} />);
+  expect(screen.getByText(/waiting for the component's first state/)).toBeInTheDocument();
+
+  act(() => FakeSocket.last?.deliver({ type: "state-update", state: { ticks: 3 } }));
+  expect(screen.getByText("3 ticks")).toBeInTheDocument();
+});
+`;
+
 const MAIN_TSX = `import React from "react";
 import ReactDOM from "react-dom/client";
 import App from "./App.tsx";
@@ -263,9 +298,12 @@ export function dashboardFiles(ctx: ShapeContext): GeneratedFile[] {
     { path: "dashboard/package.json", content: packageJson(ctx) },
     { path: "dashboard/tsconfig.json", content: TSCONFIG },
     { path: "dashboard/vite.config.ts", content: VITE_CONFIG_TS },
+    { path: "dashboard/vitest.config.ts", content: VITEST_CONFIG_TS },
     { path: "dashboard/index.html", content: indexHtml(ctx) },
     { path: "dashboard/src/main.tsx", content: MAIN_TSX },
     { path: "dashboard/src/App.tsx", content: APP_TSX },
+    { path: "dashboard/src/App.test.tsx", content: APP_TEST_TSX },
+    { path: "dashboard/src/test/setup.ts", content: TEST_SETUP_TS },
     { path: "dashboard/src/api.ts", content: API_TS },
     { path: "dashboard/src/index.css", content: INDEX_CSS },
     { path: "backend/src/lib/dashboards.ts", content: BACKEND_LIB_DASHBOARDS_TS },

package/create-product/features/frontend.ts

@@ -13,6 +13,7 @@
 // three independent edits, and why the dev script builds dist before starting
 // the backend that serves it.
 import type { GeneratedFile, ShapeContext } from "../create-product.ts";
+import { TEST_SETUP_TS, UI_TEST_DEV_DEPENDENCIES, VITEST_CONFIG_TS } from "./ui-tests.ts";
 
 export const CONFIG_SCREEN_URL = "/configure";
 
@@ -31,6 +32,7 @@ function packageJson(ctx: ShapeContext): string {
         build: "bunx vite build",
         clean: "rm -rf dist",
         typecheck: "bunx tsc --noEmit",
+        test: "vitest run",
       },
       dependencies: {
         [`${ctx.scope}/shared`]: "workspace:*",
@@ -44,6 +46,7 @@ function packageJson(ctx: ShapeContext): string {
         "@vitejs/plugin-react": "^6.0.1",
         typescript: "^5.7.2",
         vite: "^8.0.0",
+        ...UI_TEST_DEV_DEPENDENCIES,
       },
     },
     null,
@@ -141,6 +144,18 @@ export default function App() {
 `;
 }
 
+function appTestTsx(ctx: ShapeContext): string {
+  return `import { render, screen } from "@testing-library/react";
+import { expect, test } from "vitest";
+import App from "./App.tsx";
+
+test("names the product", () => {
+  render(<App />);
+  expect(screen.getByRole("heading", { name: "${ctx.name}" })).toBeInTheDocument();
+});
+`;
+}
+
 const INDEX_CSS = `:root {
   color-scheme: light dark;
   font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
@@ -157,9 +172,12 @@ export function frontendFiles(ctx: ShapeContext): GeneratedFile[] {
     { path: "frontend/package.json", content: packageJson(ctx) },
     { path: "frontend/tsconfig.json", content: TSCONFIG },
     { path: "frontend/vite.config.ts", content: VITE_CONFIG_TS },
+    { path: "frontend/vitest.config.ts", content: VITEST_CONFIG_TS },
     { path: "frontend/index.html", content: indexHtml(ctx) },
     { path: "frontend/src/main.tsx", content: MAIN_TSX },
     { path: "frontend/src/App.tsx", content: appTsx(ctx) },
+    { path: "frontend/src/App.test.tsx", content: appTestTsx(ctx) },
+    { path: "frontend/src/test/setup.ts", content: TEST_SETUP_TS },
     { path: "frontend/src/index.css", content: INDEX_CSS },
   ];
 }

package/create-product/features/ui-tests.ts

@@ -0,0 +1,44 @@
+// The test runner the two screen workspaces (frontend/, dashboard/) share:
+// vitest under jsdom with testing-library, run by the root `test:unit`, so the
+// product's one test command covers the screens too.
+
+export const UI_TEST_DEV_DEPENDENCIES = {
+  "@testing-library/jest-dom": "^6.9.1",
+  "@testing-library/react": "^16.3.2",
+  jsdom: "^29.0.1",
+  vitest: "^4.1.3",
+};
+
+// Like vite.config.ts, kept out of the tsconfig `include`: it imports the
+// bundler.
+export const VITEST_CONFIG_TS = `import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vitest/config";
+
+// One React instance: alias to the pair react-dom loads, so testing-library
+// cannot pull in a second copy (every hook then throws).
+const require = createRequire(import.meta.url);
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: { react: dirname(require.resolve("react")), "react-dom": dirname(require.resolve("react-dom")) },
+    dedupe: ["react", "react-dom"],
+  },
+  test: {
+    include: ["src/**/*.test.{ts,tsx}"],
+    environment: "jsdom",
+    setupFiles: ["./src/test/setup.ts"],
+  },
+});
+`;
+
+// Without vitest globals, testing-library cannot register its own cleanup, so
+// renders would pile up across tests in one document.
+export const TEST_SETUP_TS = `import "@testing-library/jest-dom/vitest";
+import { cleanup } from "@testing-library/react";
+import { afterEach } from "vitest";
+
+afterEach(cleanup);
+`;

package/create-product/turnkey.ts

@@ -158,6 +158,9 @@ shared core.
 
 function claudeTail(ctx: ShapeContext): string {
   const workspaceNotes = featureNotes(ctx);
+  const screens = (["dashboard", "frontend"] as const).filter((f) => ctx.features.has(f));
+  const screenTests =
+    screens.length === 0 ? "" : `, then the vitest suites of ${screens.map((s) => `\`${s}/\``).join(" and ")} (jsdom)`;
   return `${workspaceNotes}## Getting norsk-ctl + the dev loop
 
 \`norsk-ctl\` (the daemon/CLI) is **not** an npm dep — it's the released binary,
@@ -285,7 +288,7 @@ refreshed \`~/.norsk-ctl/product-templates/<name>/compose.yml\` carries the pins
 Byte-snapshots (\`tests/unit/workflow-snapshot.test.ts\`) pin the emitted wire
 bytes; \`UPDATE_SNAPSHOTS=1\` refreshes deliberately.
 
-- \`bun run test\` / \`test:unit\` — shared/backend units + tests/unit scaffolds.
+- \`bun run test\` / \`test:unit\` — shared/backend units + tests/unit scaffolds${screenTests}.
 - \`bun run test:image\` — image smoke test (needs Docker + \`bun run build:image\`):
   runs the built container and asserts the surface \`product add\` probes.
 - \`bun run check:drift\` — the shared-conventions gate; CI runs it plus
@@ -322,13 +325,17 @@ function rootPackageJson(ctx: ShapeContext): string {
         lint: "biome check .",
         "lint:fix": "biome check --write .",
         test: "bun run test:unit",
-        "test:unit": `bun test shared/src/ backend/src/ ${hasComponents ? "components/src/ " : ""}tests/unit/`,
+        "test:unit": [
+          `bun test shared/src/ backend/src/ ${hasComponents ? "components/src/ " : ""}tests/unit/`,
+          ...(hasDashboard ? ["bun run --cwd dashboard test"] : []),
+          ...(hasFrontend ? ["bun run --cwd frontend test"] : []),
+        ].join(" && "),
         "test:image": "bun test tests/image/",
         "test:smoke": "NORSK_CTL_ENV=test bun test tests/smoke.spec.ts",
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
         "docs:check":
           "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/light-pages.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/journeys.ts",
-        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/operating.md docs/known-limitations.md`,
+        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/administering.md docs/operating.md docs/known-limitations.md`,
         "docs:handover": "bash scripts/docs-handover.sh",
         "docs:handover:check": "bash scripts/docs-handover.sh --check",
         // The docs SITE (website/) — a standalone package, so its install is its
@@ -2044,7 +2051,8 @@ norsk-ctl and the pinned Norsk SDK:
 Two channels, deliberately:
 
 - **The bundle the image serves.** \`bun run docs:manual\` builds it from
-  \`docs/handover.md\`, \`docs/operating.md\` and \`docs/known-limitations.md\`;
+  \`docs/handover.md\`, \`docs/administering.md\`, \`docs/operating.md\` and
+  \`docs/known-limitations.md\`;
   the image build runs
   it, so every image serves them at /docs at the version that is running
   (linked from the product's page in norsk-ctl). \`bun run docs:handover\`
@@ -2070,6 +2078,7 @@ served at /docs at the version that is running.
 | Document                     | Audience                                  | What it is                                                                                          |
 | ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
 | \`docs/handover.md\`          | whoever gets this product running         | How norsk-ctl arrives, the one command that adds this product, and the bundle route for platform teams |
+| \`docs/administering.md\`     | the server's administrator                | What runs on the server and where, how to reach it, update it, back it up and remove it            |
 | \`docs/operating.md\`         | operators                                 | What a running deployment looks like from the operator's chair: the controls, the checks, the signs |
 | \`docs/known-limitations.md\` | operators                                 | What the product does not do yet, with the consequence and the workaround                          |
 
@@ -2113,7 +2122,7 @@ the Administrator's hat._
 | Evaluator     | \`/docs/\`           | \`/docs/guides/\`                        | [norsk-ctl's manual](https://ctl.norsk.video/), to run it for real      |
 | Builder       | \`/docs/guides/\`    | \`/docs/how-to/\`                        | \`/docs/reference/\`, for the settings they just used                    |
 | Integrator    | \`/docs/reference/\` | \`/docs/concepts/\`                      | [norsk-ctl's CLI and API reference](https://ctl.norsk.video/)           |
-| Administrator | \`handover.md\`      | \`operating.md\`, \`known-limitations.md\` | [norsk-ctl's manual](https://ctl.norsk.video/), for everything about the machine |
+| Administrator | \`handover.md\`      | \`administering.md\`, \`operating.md\`, \`known-limitations.md\` | [norsk-ctl's manual](https://ctl.norsk.video/), for everything about the machine |
 
 Site paths resolve under website/src/content/docs; a bare name resolves under
 docs/. Each route is at most five pages and ends in a hand-off, which is the
@@ -2218,6 +2227,122 @@ and its health check at /healthz are for._
 `;
 }
 
+// The server admin's page: the product running under norsk-ctl on the
+// customer's own machine (gameplay-football247's dev-ops guide, generalised).
+// norsk-ctl's server install is the same everywhere, so its half is written
+// out; the product's half carries a marker per section.
+function administeringMd(ctx: ShapeContext): string {
+  return `# Administering ${ctx.name}
+
+For whoever looks after the server ${ctx.name} runs on: what is installed
+where, how to reach it, how to update it, and how to remove it. Getting it
+running the first time is in handover.md; running the product day to day is in
+operating.md.
+
+## What runs on the server
+
+${ctx.name} runs under **norsk-ctl**, Norsk's service manager.
+
+| Process / container | What it is |
+|---|---|
+| \`norsk-ctl\` (systemd service) | The manager: launches and supervises ${ctx.name}, serves its API |
+| \`norsk-proxy\`, \`norsk-proxy-oauth2\` | The HTTPS entry point and its login |
+| \`norsk-product-${ctx.name}\` | The product's control plane |
+| \`<instance>-<service>-1\` | One per service of a launched instance |
+
+<!-- ctl-docs-template: fill me -->
+_Name this product's instance containers and say what each one does (the
+starter's are Studio, the workflow and its dashboard, and the media engine)._
+
+## Where things are
+
+| Path | Contents |
+|---|---|
+| \`/etc/norsk-ctl/\` | norsk-ctl's configuration (\`config.yaml\`), licences, TLS certificate |
+| \`/var/lib/norsk-ctl/\` | norsk-ctl's state: database, product registry, templates, proxy |
+| \`/var/log/norsk-ctl/\` | norsk-ctl's logs |
+| \`/opt/norsk-ctl/bin/\` | norsk-ctl binaries, one per version; \`/usr/local/bin/norsk-ctl\` points at the current one |
+| \`/etc/systemd/system/norsk-ctl.service\` | The service unit |
+| \`/etc/sysctl.d/90-norsk-tuning.conf\` | Network buffer tuning for media |
+<!-- path-allow -->
+
+<!-- ctl-docs-template: fill me -->
+_Add the instance's working directory (uploaded media, settings) and anything
+else this product keeps on disk._
+
+norsk-ctl runs as the user \`norsk\`. Run its CLI as that user, with its
+configuration:
+
+\`\`\`sh
+sudo -u norsk env NORSK_CTL_CONFIG_DIR=/etc/norsk-ctl NORSK_CTL_STATE_DIR=/var/lib/norsk-ctl \\
+  NORSK_CTL_LOG_DIR=/var/log/norsk-ctl norsk-ctl instance list
+\`\`\`
+
+## Network
+
+<!-- ctl-docs-template: fill me -->
+| Port | Open to | What |
+|---|---|---|
+| 22/tcp | administrators | SSH |
+| _443/tcp_ | _operators_ | _The web page (or loopback only: see below)_ |
+| _the product's inputs and outputs_ | _the senders and receivers_ | _one row per media port_ |
+
+## Reaching the web page
+
+The web page is norsk-ctl's proxy. On a server that must not expose it, bind it
+to loopback (norsk-ctl's \`bindAddress\` setting) and reach it through an SSH
+tunnel:
+
+\`\`\`sh
+ssh -L 8443:127.0.0.1:443 <you>@<server>   # 443: the proxy's port, if unchanged
+# then browse https://localhost:8443
+\`\`\`
+
+A self-signed certificate is accepted once in the browser.
+
+## Installing and updating
+
+<!-- ctl-docs-template: fill me -->
+_The release this product ships and the one command that installs or updates
+it, with the settings it takes. Without a release kit: norsk-ctl's installer,
+then \`norsk-ctl product add\` (handover.md); a new image is \`norsk-ctl product
+reload\`; norsk-ctl itself is \`norsk-ctl upgrade --version <v>\`, as root._
+
+## Checking it is healthy
+
+\`\`\`sh
+systemctl status norsk-ctl     # the manager
+journalctl -u norsk-ctl -f     # its log
+docker ps                      # every container above, Up
+\`\`\`
+
+<!-- ctl-docs-template: fill me -->
+_What the product's own page shows when it is healthy, and which container's
+log to read first when it is not._
+
+## Removing it
+
+<!-- ctl-docs-template: fill me -->
+_How to remove the product, and norsk-ctl with it, and what is left behind.
+Say plainly what is deleted (uploaded media) and how to keep it._
+
+## Backups
+
+norsk-ctl's state worth keeping is \`/etc/norsk-ctl\` and \`/var/lib/norsk-ctl\`,
+plus each instance's working directory.
+
+<!-- ctl-docs-template: fill me -->
+_Anything else of this product's that is worth keeping._
+
+## Licence
+
+${ctx.name} runs under a Norsk licence that entitles it, staged in
+\`/etc/norsk-ctl/licenses/\`. The product takes its licence when it is added
+(\`norsk-ctl product add --license-file\`), so a new licence goes in with the
+next \`product add\`.
+`;
+}
+
 const KNOWN_LIMITATIONS_MD = `# Known limitations
 
 What this product does not do yet, or does with a caveat an operator must know
@@ -2298,6 +2423,7 @@ export const turnkey: ShapeModule = {
       { path: "docs/README.md", content: docsReadmeMd(ctx) },
       { path: "docs/handover.md", content: handoverMd(ctx) },
       { path: "docs/operating.md", content: operatingMd(ctx) },
+      { path: "docs/administering.md", content: administeringMd(ctx) },
       { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },
       { path: "docs/personas.md", content: personasMd(ctx) },
       { path: ".github/workflows/build-docs.yml", content: ctx.canon.buildDocs },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.77",
+  "version": "0.2.79",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
@@ -44,16 +44,22 @@
     "@norskvideo/norsk-studio-builder": "1.30.0-2026-10-12-34c09bda",
     "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-12-34c09bda",
     "@playwright/test": "^1.59.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
     "@types/cors": "^2.8.17",
     "@types/express": "5",
     "@types/node": "^22.10.0",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^6.0.1",
     "cors": "^2.8.5",
     "express": "5",
+    "jsdom": "^29.0.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.3",
     "yaml": "^2.8.0",
     "zod": "4.4.3"
   },