@norskvideo/ctl-dev-kit 0.2.106 → 0.2.108

package/conventions/checks.sdk-app.yml

@@ -246,11 +246,18 @@ jobs:
       # The image name is CI's own rule: PUBLISH_IMAGE when set, else the build
       # script's IMAGE_TAG default, tag stripped -- a licence matches the repo
       # part alone, never the tag.
+      #
+      # PRODUCT_NAME is read as smoke.yml reads it: an sdk-app keeps it in
+      # src/product/version.ts (norsk-relay) or shared/src/version.ts
+      # (norsk-conversion); the first that exists is read.
       - name: Check this repo records its own licence
         run: |
           set -euo pipefail
-          product="$(sed -nE 's/.*PRODUCT_NAME[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/p' src/product/version.ts | head -1)"
-          [ -n "$product" ] || { echo "::error::could not read PRODUCT_NAME from src/product/version.ts"; exit 1; }
+          vf=""
+          for f in shared/src/version.ts src/product/version.ts; do [ -f "$f" ] && { vf="$f"; break; }; done
+          [ -n "$vf" ] || { echo "::error::no shared/src/version.ts or src/product/version.ts"; exit 1; }
+          product="$(sed -nE 's/.*PRODUCT_NAME[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/p' "$vf" | head -1)"
+          [ -n "$product" ] || { echo "::error::could not read PRODUCT_NAME from $vf"; exit 1; }
           pub="$(sed -nE 's/^[[:space:]]*PUBLISH_IMAGE:[[:space:]]*"?([^" ]*)"?[[:space:]]*$/\1/p' .github/workflows/build-image.yml | head -1)"
           def="$(sed -nE 's/.*IMAGE_TAG:-([^}]+)\}.*/\1/p' deployment/build-image.sh | head -1)"
           ref="${pub:-$def}"

package/create-demo/create-demo.ts

@@ -0,0 +1,191 @@
+// `ctl-dev-kit create-demo` — renders a new customer demo repo: a Studio
+// working directory, the scripts that install it into norsk-ctl, and the docs
+// that make every demo look the same. Unlike create-product, the output is
+// copied once and then owned by the customer: there is no drift gate, no CI and
+// no canonical bytes to stay in step with.
+//
+// The files live under template/ as real files, with `__DEMO__` where the demo's
+// name goes, so they can be read and edited as what they are:
+//   template/core/       every demo
+//   template/<feature>/  added by --with <feature>
+// Markdown is kept as `<name>.md.tmpl` and emitted as `<name>.md`: as a .md the
+// repo's formatter would rewrite it (`__DEMO__` becomes bold, and the feature
+// markers split its tables). It may carry `<!-- if:<feature> -->` ...
+// `<!-- end:<feature> -->` blocks, kept when that feature is on and dropped
+// when it is off. `gitignore` is emitted as `.gitignore`: npm drops a
+// .gitignore from a published package.
+//
+// The components feature is not a template: it is create-product's components/
+// workspace (its build chain and example node), without the product glue.
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { type GeneratedFile, shapeContext } from "../create-product/create-product.ts";
+import { componentsWorkspaceFiles, EXAMPLE_IDENTIFIER } from "../create-product/features/components.ts";
+
+// - dashboard   an operator dashboard, built into the workflow's dashboards/
+//               and served by Studio at /dashboard/<name>/
+// - components  this demo's own Studio nodes, built into the working dir's
+//               components/, where norsk-ctl finds and mounts them
+export type DemoFeature = "dashboard" | "components";
+
+const ALL_FEATURES: readonly DemoFeature[] = ["dashboard", "components"];
+
+export interface CreateDemoOptions {
+  /** The demo's name: its workflow, its norsk-ctl instance and its library scope. */
+  name: string;
+  /** Whose `.ai/<user>/tasks/` the seeded task file goes in. */
+  user: string;
+  withFeatures?: DemoFeature[];
+}
+
+const TOKEN = "__DEMO__";
+const TEMPLATE_DIR = join(import.meta.dir, "template");
+
+function resolveFeatures(names: DemoFeature[] | undefined): Set<DemoFeature> {
+  for (const name of names ?? []) {
+    if (!ALL_FEATURES.includes(name)) {
+      throw new Error(`unknown feature ${JSON.stringify(name)} in --with — features: ${ALL_FEATURES.join(", ")}.`);
+    }
+  }
+  return new Set(names ?? []);
+}
+
+function* walk(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir).sort()) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) yield* walk(full);
+    else yield full;
+  }
+}
+
+function featureBlocks(text: string, features: ReadonlySet<DemoFeature>): string {
+  return text.replace(/^<!-- if:(\w+) -->\n([\s\S]*?)^<!-- end:\1 -->\n/gm, (_, feature: DemoFeature, body: string) =>
+    features.has(feature) ? body : "",
+  );
+}
+
+function templateFiles(layer: string, name: string, features: ReadonlySet<DemoFeature>): GeneratedFile[] {
+  const root = join(TEMPLATE_DIR, layer);
+  return [...walk(root)].map((full) => {
+    const rel = relative(root, full);
+    const markdown = rel.endsWith(".md.tmpl");
+    const emitted = rel === "gitignore" ? ".gitignore" : markdown ? rel.slice(0, -".tmpl".length) : rel;
+    const raw = readFileSync(full, "utf8");
+    const path = emitted.replaceAll(TOKEN, name);
+    const content = (markdown ? featureBlocks(raw, features) : raw).replaceAll(TOKEN, name);
+    return { path, content, executable: /^(ctl|scripts)\/.*\.sh$/.test(path) };
+  });
+}
+
+function workflowYaml(name: string, features: ReadonlySet<DemoFeature>): string {
+  const example = features.has("components")
+    ? `
+  # The placeholder from components/: it carries no media, publishes a heartbeat
+  # and serves /status. Delete it, and components/src/library/example/, once a
+  # real component exists.
+  - type: ${EXAMPLE_IDENTIFIER}
+    config:
+      id: example
+      displayName: Example
+      heartbeatMs: 1000
+    subscriptions: []
+`
+    : "";
+  const exampleLayout = features.has("components") ? "  - { id: example, x: 480, y: 300 }\n" : "";
+  return `# ${name}: the starter workflow.
+#
+# srt_in ─► preview
+#
+# srt_in is an SRT listener for a camera or an encoder to send to
+# (scripts/test-feed.sh sends a test picture). preview is a still of its
+# picture, which Studio's editor and the dashboard show. Replace this with the
+# demo's real graph, keeping the comments and the __layout block in step.
+#
+# Site settings (ports, passphrases, destinations) are not set here: they come
+# from ctl/studio.env as Studio environment overrides, <ID>_<FIELD>.
+components:
+  - type: input.srt-listener
+    config:
+      id: srt_in
+      displayName: SRT In
+      # Published on the host by HOST_PORTS in ctl/site.env; change both together.
+      port: 5001
+      host: 0.0.0.0
+      sourceNames: permissive
+      streamIds: [camera]
+    subscriptions: []
+  - type: output.preview
+    config:
+      id: preview
+      displayName: Preview
+      # A JPEG, refreshed: it needs no media ports, so it works in norsk-ctl's
+      # docker network mode. moq mode gives live video the same way.
+      previewMode: image
+      showPreview: true
+    subscriptions:
+      - source: srt_in
+        streams: { type: take-first-stream, filter: [{ media: video }] }
+${example}__layout:
+  - { id: srt_in, x: 0, y: 0 }
+  - { id: preview, x: 480, y: 0 }
+${exampleLayout}`;
+}
+
+function taskFile(name: string, features: ReadonlySet<DemoFeature>): string {
+  const withs = features.size > 0 ? ` --with ${[...features].join(",")}` : "";
+  return `# ${name} demo
+
+**Started:** generated by \`ctl-dev-kit create-demo --name ${name}${withs}\`.
+
+## STATUS (current)
+
+Scaffold only: the starter workflow (SRT in, image preview) installs and runs.
+Nothing demo-specific is built yet.
+
+### Open / not done
+- TODO: what the customer asked to see.
+
+## Brief
+
+TODO: who the customer is, what the demo must show, when and where it is shown,
+and what they take away afterwards.
+
+## Decisions
+
+| Decision | Status | Outcome |
+|---|---|---|
+
+## Log
+`;
+}
+
+export function planDemo(opts: CreateDemoOptions): GeneratedFile[] {
+  // An instance id, a workflow file name and an npm scope all at once.
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(opts.name)) {
+    throw new Error(
+      `invalid demo name ${JSON.stringify(opts.name)} — a lowercase letter, then lowercase letters, digits and hyphens; 1-40 chars (it names the norsk-ctl instance, the workflow and the components' npm scope).`,
+    );
+  }
+  const features = resolveFeatures(opts.withFeatures);
+  const { name } = opts;
+  const files = [
+    ...templateFiles("core", name, features),
+    { path: `workdir/studio-save-files/${name}/${name}.yaml`, content: workflowYaml(name, features) },
+    { path: `.ai/${opts.user}/tasks/${name}-demo.md`, content: taskFile(name, features) },
+  ];
+  if (features.has("dashboard")) files.push(...templateFiles("dashboard", name, features));
+  if (features.has("components")) {
+    files.push(...componentsWorkspaceFiles(shapeContext({ dir: "", name, shape: "backend-turnkey" })));
+  }
+  return files;
+}
+
+export function createDemo(opts: CreateDemoOptions & { dir: string }): { files: string[] } {
+  const plan = planDemo(opts);
+  for (const file of plan) {
+    const path = join(opts.dir, file.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, file.content, { mode: file.executable ? 0o755 : 0o644 });
+  }
+  return { files: plan.map((f) => f.path) };
+}

package/create-demo/template/core/CLAUDE.md.tmpl

@@ -0,0 +1,158 @@
+# __DEMO__: a Norsk Studio demo
+
+This repo is a customer demo: a Studio workflow, plus what it needs around it,
+built by us, shown to the customer, then handed over for them to develop. It is
+not a product: there is no CI, no drift gate and no test tiers, and after
+handover the customer owns every file in it. Keep it small enough that someone
+new to Norsk can read the whole thing.
+
+It was generated by `ctl-dev-kit create-demo`, so its layout matches every other
+demo. Keep to it: anyone in the team should be able to pick this up and find
+things where they expect.
+
+## Layout
+
+| Path                                               | What it is                                                                                                 |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `workdir/`                                         | The Studio working directory, staged as-is on the box and mounted at `/data`                               |
+| `workdir/studio-save-files/__DEMO__/__DEMO__.yaml` | The workflow. Hand-edited and commented; the `__layout` block places nodes in the editor                   |
+| `ctl/`                                             | Installing into norsk-ctl: `install.sh`, `push.sh`, `mode.sh`, the shared `lib.sh` and the site's settings |
+| `scripts/build.sh`                                 | Builds what the demo adds to Studio into `workdir/`                                                        |
+| `scripts/test-feed.sh`                             | `up`/`down` a test picture into the SRT input                                                              |
+<!-- if:dashboard -->
+| `dashboard/` | The operator dashboard, a vite app Studio serves at `/dashboard/__DEMO__/` |
+<!-- end:dashboard -->
+<!-- if:components -->
+| `components/` | This demo's own Studio nodes, the `@__DEMO__/library` library |
+<!-- end:components -->
+| `README.md` | The customer's handover document. Keep it true as the demo changes |
+| `.ai/<user>/tasks/` | Task files: what was asked, what was decided, what is left |
+
+## How it runs
+
+norsk-ctl is the only run path, here and on the customer's box. ctl provides
+TLS, ports and Studio's config, so this repo has no compose file, proxy or certs.
+The demo is one instance, `__DEMO__`, launched from the `studio-dev` product
+template with `workdir/` as its working directory.
+
+1. `cp ctl/site.example.env ctl/site.env` and `cp ctl/studio.example.env ctl/studio.env`, then fill them in.
+   `site.env` says where the demo runs (here, or `DEMO_HOST=user@box`); `studio.env` holds the workflow's
+   site settings.
+2. `ctl/install.sh` the first time. It builds, stages `workdir/` at `WORKDIR` owned by the norsk-ctl
+   user, and launches the instance.
+3. `ctl/push.sh` after every change. It builds, syncs, relaunches and waits until Studio is up.
+4. `ctl/mode.sh editor` to change the workflow in Studio's editor; `ctl/mode.sh document` to put it back
+   to running on start.
+5. `scripts/test-feed.sh up` for a picture without a camera.
+
+The scripts print the Studio URL. The same scripts serve a local norsk-ctl and
+the customer's box, so what is shown is what was tested.
+
+A customer who wants the demo out of norsk-ctl uses
+`norsk-ctl instance export __DEMO__ --to <dir>`, which writes a compose bundle
+with its own `HANDOVER.md`. It refuses a different compose project name (`-p`),
+and it has no proxy: the deployer supplies `NORSK_PUBLIC_BASE_URL` and a
+reverse proxy for `/instance/__DEMO__/studio`.
+
+## Working rules
+
+- **The YAML is the source.** Edit `__DEMO__.yaml` by hand, keep its comments,
+  and keep `__layout` in step when nodes are added. Saving from Studio's editor
+  strips comments and `__layout`; if a change was made there, copy the shape
+  back by hand rather than committing the editor's file.
+- **Site settings are not in the YAML.** Ports, passphrases and destinations go
+  in `ctl/studio.env` as `<COMPONENT_ID>_<FIELD>=value`, for fields the
+  component declares overridable. A `${VAR}` in a YAML value fails validation.
+- **Component ids are an interface.** The dashboard, `studio.env` and the README
+  all name them. Rename one everywhere or not at all.
+- **Ports:** let norsk-ctl allocate them. Pin one in `HOST_PORTS` only when a
+  sender or a firewall outside the box must agree on it. On a shared box, never
+  stop another instance's containers.
+- **Push, then check.** After `ctl/push.sh`, open the URL it prints and look:
+  a relaunch that came up is not a workflow that works.
+- **The README is the handover.** When something changes what the customer
+  sees or does, change the README in the same commit.
+
+## Gotchas
+
+- Under norsk-ctl the working dir must be owned by the norsk-ctl user, and on a
+  path it can reach: `/srv/__DEMO__`, not a home directory.
+- `STUDIO_DOCUMENT` does nothing under norsk-ctl, which writes Studio's config
+  itself. The document comes from `NODE_CONFIG` in the overrides, which is what
+  `ctl/mode.sh` switches.
+- `NODE_CONFIG` replaces the library list norsk-ctl writes, so the overrides
+  name every library. `ctl/lib.sh` does this; keep it if you edit it.
+- A fixed document hides the editor's Stop button. Use `ctl/mode.sh editor`.
+- Studio's `/api/files` refuses to overwrite: a write is DELETE then POST.
+- Put a `processor.smartSourceSwitch` with a fallback after inputs, or a source
+  dropping resets HLS. Silence-fill audio that comes and goes, so nothing
+  renegotiates.
+- A WHEP return carries one audio stream; WHIP clients should DELETE the
+  session on pagehide.
+- WebRTC media (WHEP, WHIP) to a viewer needs `NETWORK_MODE=hybrid`. MoQ and
+  image previews work in docker mode.
+- The microphone and MoQ/WebTransport need HTTPS. norsk-ctl serves HTTPS.
+- Studio's COOP header stops a Studio-served page painting in a
+  `processor.browserOverlay`: use `--disable-features=CrossOriginOpenerPolicy`
+  in `customCefArgs`, or a `file:///data/...` URL.
+- Headless browser tests need Debian's chromium: Playwright's own build has no
+  H.264.
+
+<!-- if:dashboard -->
+
+## Dashboard
+
+`dashboard/` is a vite + React app with one page per HTML entry. `scripts/build.sh`
+builds it into `workdir/studio-save-files/__DEMO__/dashboards/`, and Studio serves
+that at `/dashboard/__DEMO__/` beside the workflow. A top-level
+`workdir/dashboards/` is not served.
+
+- `src/lib/workflow.ts` is the one place the dashboard names component ids.
+  Keep it in step with the YAML.
+- Each page fetches `./env` for `apiBasePath` and `wsBasePath`, so it works
+  under any URL prefix. Never hard-code `/live` or a host.
+- The hooks are the dashboard's whole Studio API:
+  - `useEnv`: the env.
+  - `useDiscovery`: the running components, polled until the workflow is up.
+  - `useLiveComponent`: a component's state over its websocket, with
+    reconnect, and `sendCommand`.
+  - `useAlerts`: a component's alerts, polled.
+- The starter preview is `output.preview` in image mode: a JPEG URL in the
+  component's state. For live video, switch the preview to `moq` mode and use a
+  MoQ player; livemode and eurovision have one (`moq-player.tsx`).
+- `bun run dev` serves the pages with Studio's routes proxied to `STUDIO_URL`,
+  which must be a Studio reachable without the sign-in proxy in front.
+<!-- end:dashboard -->
+<!-- if:components -->
+
+## Custom components
+
+`components/` is this demo's own Studio library, `@__DEMO__/library`, with one
+placeholder node, `output.example`. `scripts/build.sh` builds it and copies
+`lib/library/` to `workdir/components/@__DEMO__/library/`. norsk-ctl finds
+packages under the working dir's `components/` and mounts them, and the
+overrides name the library, so Studio loads it.
+
+- A component is a directory under `src/library/` with `info.ts` (design time:
+  config form, subscriptions), `runtime.ts` (the media nodes and routes) and
+  `types.source.yaml` (the schema; `_gen/types.ts` is generated from it). Adding
+  one is adding a directory: `index.ts` registers every one it finds.
+- The build order is load-bearing: codegen, then tsc to CommonJS, then
+  `copy-yamls.ts`, which writes `types.yaml` beside each runtime and a browser
+  bundle of `info.ts`. That bundle must not import react or `@norskvideo/*` as
+  bare specifiers; `info-client-externals.test.ts` checks it.
+- Publish a component's state from its constructor: Studio refuses websocket
+  connections while a state is undefined.
+- Keep the pure logic in sibling modules, testable with `bun test` and no Studio.
+- Delete `example/` (and its node in the YAML) once a real component exists.
+<!-- end:components -->
+
+## Handover
+
+Before the customer takes it:
+
+- The README is complete: install, URLs, the workflow block by block, how to
+  change it, what it does not do, versions, and how to take it out of norsk-ctl.
+- `ctl/site.example.env` and `ctl/studio.example.env` describe every setting.
+- The task file says what was shown and what is left.
+- Nothing in the repo is a site's secret.

package/create-demo/template/core/README.md.tmpl

@@ -0,0 +1,74 @@
+# __DEMO__
+
+<!-- The customer's handover document. Replace every TODO before handover; the
+     CLAUDE.md "Handover" list says what this needs to cover. -->
+
+TODO: one paragraph on what this demo does and who it is for.
+
+## What is in it
+
+| Path       | What it is                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------ |
+| `workdir/` | The Norsk Studio working directory: the workflow, and what Studio serves and loads with it |
+| `ctl/`     | The scripts that install it into norsk-ctl and update it                                   |
+| `scripts/` | Building it, and a test feed                                                               |
+<!-- if:dashboard -->
+| `dashboard/` | The operator dashboard |
+<!-- end:dashboard -->
+<!-- if:components -->
+| `components/` | This demo's own Studio components |
+<!-- end:components -->
+
+## Installing
+
+It runs under norsk-ctl, on this machine or another one over ssh.
+
+1. Install norsk-ctl on the machine, and have the norsk-studio licence there.
+2. Copy `ctl/site.example.env` to `ctl/site.env` and fill it in: where it runs, where the working
+   dir goes, the licence path, the ports to publish.
+3. Copy `ctl/studio.example.env` to `ctl/studio.env` and fill in the site's settings.
+4. Run `ctl/install.sh`. It prints the Studio URL when it is up.
+
+Building needs bun on the machine you run the scripts from.
+
+## Using it
+
+TODO: the URLs, and what the operator does on each page.
+
+- `scripts/test-feed.sh up` sends a test picture into the SRT input; `down` stops it.
+
+## The workflow
+
+TODO: each block in `workdir/studio-save-files/__DEMO__/__DEMO__.yaml`, in signal
+order: what it is for and the settings that matter.
+
+## Changing it
+
+- Edit the workflow YAML, then `ctl/push.sh`. It rebuilds, copies the working dir over and relaunches.
+- To change it in Studio's editor, `ctl/mode.sh editor`; `ctl/mode.sh document` puts it back to
+  running on start. Saving from the editor drops the YAML's comments, so copy changes back by hand.
+- Site settings (ports, passphrases, destinations) live in `ctl/studio.env`, as
+  `<COMPONENT_ID>_<FIELD>=value`.
+<!-- if:dashboard -->
+- The dashboard is in `dashboard/`; `src/lib/workflow.ts` names the components it shows.
+<!-- end:dashboard -->
+<!-- if:components -->
+- Custom components are in `components/src/library/`, one directory each.
+<!-- end:components -->
+
+## Limits
+
+TODO: what this demo does not do, and what a production build would add.
+
+There is no access control beyond norsk-ctl's own sign-in.
+
+## Versions
+
+TODO: the norsk-ctl, Studio and Norsk versions this was shown on
+(`norsk-ctl instance describe __DEMO__`).
+
+## Taking it out of norsk-ctl
+
+`norsk-ctl instance export __DEMO__ --to <dir>` writes a docker compose bundle that runs
+without norsk-ctl, with a `HANDOVER.md` of its own. Run it under its own project name, and put
+a reverse proxy in front of Studio: the bundle has none.

package/create-demo/template/core/ctl/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# First install of the demo into norsk-ctl: here, or on DEMO_HOST over ssh
+# (see ctl/site.env). Builds, stages workdir/ at WORKDIR, and launches it as
+# instance __DEMO__ from the studio-dev template. ctl/push.sh updates it after.
+#
+#   ctl/install.sh [--no-build]
+source "$(dirname "$0")/lib.sh"
+load_site
+
+if ctl instance exists "$DEMO" >/dev/null 2>&1; then
+  die "instance $DEMO already exists: ctl/push.sh updates it"
+fi
+if [[ "${1:-}" != --no-build ]]; then "$ROOT/scripts/build.sh"; fi
+
+ensure_template
+sync_workdir
+write_overrides "$(current_mode)"
+
+ports=()
+for port in $HOST_PORTS; do ports+=(--host-ports "$port"); done
+ctl instance launch-template "$DEMO" --template studio-dev \
+  --param "INSTANCE_NAME=$DEMO" --param GLOBAL_MOQ_PREVIEW_WEBTRANSPORTPORT=auto \
+  --working-directory "$WORKDIR" --overrides "$WORKDIR/ctl-overrides.yml" \
+  --network-mode "$NETWORK_MODE" "${ports[@]}" >/dev/null
+
+wait_ready
+print_urls

package/create-demo/template/core/ctl/lib.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# Shared by install.sh, push.sh and mode.sh: the site's settings, how to reach
+# the machine the demo runs on, and the overrides file norsk-ctl launches
+# Studio with. Sourced, not run.
+set -euo pipefail
+
+DEMO=__DEMO__
+CTL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(dirname "$CTL_DIR")"
+
+die() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+# ctl/site.env, with the defaults for anything it leaves unset.
+load_site() {
+  [[ -f "$CTL_DIR/site.env" ]] || die "no ctl/site.env: copy ctl/site.example.env to it and fill it in"
+  set -a
+  # shellcheck source=/dev/null
+  source "$CTL_DIR/site.env"
+  set +a
+  DEMO_HOST="${DEMO_HOST:-}"
+  WORKDIR="${WORKDIR:-/srv/$DEMO}"
+  NETWORK_MODE="${NETWORK_MODE:-docker}"
+  RUN_AS="${RUN_AS-norsk}"
+  NORSK_CTL="${NORSK_CTL:-norsk-ctl}"
+  HOST_PORTS="${HOST_PORTS:-}"
+  LICENSE_FILE="${LICENSE_FILE:-}"
+}
+
+quote() {
+  local out=() arg
+  for arg in "$@"; do out+=("$(printf '%q' "$arg")"); done
+  echo "${out[*]}"
+}
+
+# Run a shell command line on the target: over ssh when DEMO_HOST is set, here
+# otherwise. stdin passes through either way.
+on_target() {
+  if [[ -n "$DEMO_HOST" ]]; then ssh "$DEMO_HOST" "$*"; else bash -c "$*"; fi
+}
+
+# "sudo " when the working dir belongs to another user (RUN_AS), else nothing.
+target_sudo() {
+  if [[ -n "$RUN_AS" ]]; then echo "sudo "; fi
+}
+
+# norsk-ctl on the target, as the user its daemon runs as.
+ctl() {
+  local cmd
+  cmd="$NORSK_CTL $(quote "$@")"
+  if [[ -n "$RUN_AS" ]]; then cmd="sudo -u $(quote "$RUN_AS") -H $cmd"; fi
+  on_target "$cmd"
+}
+
+current_mode() {
+  cat "$CTL_DIR/.mode" 2>/dev/null || echo document
+}
+
+yaml_quote() {
+  local s="${1//\'/\'\'}"
+  printf "'%s'" "$s"
+}
+
+# The compose override norsk-ctl merges over the studio service, for a mode:
+#   document  Studio runs acme.yaml on start (the demo as shown)
+#   editor    Studio opens on the editor with nothing running (for changing it)
+# NODE_CONFIG names every library, the custom components included, because a
+# norsk-ctl older than the library fix lets this list replace the one it
+# writes. ctl/studio.env lines are Studio environment overrides, <ID>_<FIELD>.
+overrides_yaml() {
+  local mode="$1" libs server line
+  [[ "$mode" == document || "$mode" == editor ]] || die "unknown mode '$mode': document or editor"
+  libs='"@norskvideo/norsk-studio-built-ins","@norskvideo/norsk-studio-beta"'
+  if [[ -d "$ROOT/components" ]]; then libs="$libs,\"@$DEMO/library\""; fi
+  server="\"library\":[$libs]"
+  if [[ "$mode" == document ]]; then server="\"document\":\"$DEMO.yaml\",$server"; fi
+  echo "services:"
+  echo "  studio:"
+  echo "    environment:"
+  echo "      NODE_CONFIG: $(yaml_quote "{\"server\":{$server}}")"
+  if [[ -f "$CTL_DIR/studio.env" ]]; then
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "${line// /}" || "$line" == \#* ]] && continue
+      echo "      ${line%%=*}: $(yaml_quote "${line#*=}")"
+    done <"$CTL_DIR/studio.env"
+  fi
+}
+
+write_overrides() {
+  overrides_yaml "$1" | on_target "$(target_sudo)tee $(quote "$WORKDIR/ctl-overrides.yml") >/dev/null"
+}
+
+# Copy workdir/ to WORKDIR on the target, owned by RUN_AS. Nothing already
+# there is deleted (Studio keeps its own files in it), except inside the two
+# build outputs, where a stale file would still be served or loaded.
+sync_workdir() {
+  local dest="$WORKDIR" rsync=(rsync) opts=(-a) sub
+  on_target "$(target_sudo)mkdir -p $(quote "$WORKDIR")"
+  if [[ -n "$RUN_AS" ]]; then
+    opts+=("--chown=$RUN_AS:$RUN_AS")
+    if [[ -n "$DEMO_HOST" ]]; then opts+=(--rsync-path="sudo rsync"); else rsync=(sudo rsync); fi
+  fi
+  if [[ -n "$DEMO_HOST" ]]; then dest="$DEMO_HOST:$WORKDIR"; fi
+  "${rsync[@]}" "${opts[@]}" --exclude logs --exclude .norsk --exclude moq-certs --exclude ctl-overrides.yml \
+    "$ROOT/workdir/" "$dest/"
+  for sub in "studio-save-files/$DEMO/dashboards" components; do
+    if [[ -d "$ROOT/workdir/$sub" ]]; then
+      "${rsync[@]}" "${opts[@]}" --delete "$ROOT/workdir/$sub/" "$dest/$sub/"
+    fi
+  done
+}
+
+# The studio-dev product template, added from the licence when it is missing.
+ensure_template() {
+  if ctl template list 2>/dev/null | grep -q "name: studio-dev"; then return; fi
+  [[ -n "$LICENSE_FILE" ]] || die "norsk-ctl has no studio-dev template: set LICENSE_FILE in ctl/site.env"
+  ctl product add --license-file "$LICENSE_FILE" --product norsk-studio >/dev/null
+}
+
+describe_field() {
+  ctl instance describe "$DEMO" -o json 2>/dev/null | bun -e '
+    const text = await Bun.stdin.text();
+    let v = JSON.parse(text.slice(text.indexOf("{")));
+    for (const key of process.argv[1].split(".")) v = v?.[key];
+    console.log(v ?? "");
+  ' "$1"
+}
+
+wait_ready() {
+  local i
+  for ((i = 0; i < 90; i++)); do
+    if [[ "$(describe_field runtimeScreen.ready 2>/dev/null)" == true ]]; then return 0; fi
+    sleep 2
+  done
+  die "$DEMO did not come up within 3 minutes: see norsk-ctl instance describe $DEMO"
+}
+
+print_urls() {
+  local studio
+  studio="$(describe_field runtimeScreen.href)"
+  echo "Studio:    $studio"
+  if [[ -d "$ROOT/dashboard" ]]; then echo "Dashboard: ${studio}dashboard/$DEMO/"; fi
+  echo "Mode:      $(current_mode)"
+}

package/create-demo/template/core/ctl/mode.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Switch the installed demo between its two modes, and relaunch it:
+#   document  Studio runs the workflow on start: the demo as it is shown.
+#             The editor's Stop button is hidden in this mode.
+#   editor    Studio opens on the editor with nothing running, to change it.
+#
+#   ctl/mode.sh document|editor
+source "$(dirname "$0")/lib.sh"
+load_site
+
+mode="${1:-}"
+overrides_yaml "$mode" >/dev/null
+ctl instance exists "$DEMO" >/dev/null 2>&1 || die "no instance $DEMO yet: run ctl/install.sh first"
+
+echo "$mode" >"$CTL_DIR/.mode"
+write_overrides "$mode"
+ctl instance relaunch "$DEMO" >/dev/null
+wait_ready
+print_urls

package/create-demo/template/core/ctl/push.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Push a change to the installed demo: build, sync workdir/ to WORKDIR, rewrite
+# the overrides from ctl/studio.env, relaunch, and wait until Studio is up.
+#
+#   ctl/push.sh [--no-build]
+source "$(dirname "$0")/lib.sh"
+load_site
+
+ctl instance exists "$DEMO" >/dev/null 2>&1 || die "no instance $DEMO yet: run ctl/install.sh first"
+if [[ "${1:-}" != --no-build ]]; then "$ROOT/scripts/build.sh"; fi
+
+sync_workdir
+write_overrides "$(current_mode)"
+ctl instance relaunch "$DEMO" >/dev/null
+wait_ready
+print_urls