@norskvideo/ctl-dev-kit 0.1.97 → 0.1.99

package/create-product/features/dashboard.ts

@@ -0,0 +1,270 @@
+// The `dashboard` feature: the operator screen as a standalone vite SPA that
+// Studio serves per instance (funke's and probe's answer; see views.ts for the
+// other one). Four different paths name the same thing, and conflating them is
+// how a dashboard comes to build, pack and launch while serving a 404:
+//
+//   repo (vite outDir)      dashboards/<workflowName>/
+//   inside the tar          dashboards/<workflowName>/
+//   inside the container    studio-save-files/<workflowName>/dashboards/
+//   URL                     /dashboard/<workflowName>/
+//
+// The rename happens at ctl's mount, not here. The generated template ships
+// workflow.yml at the tar root, so the workflow is called "workflow" and the
+// directory below is not a free choice.
+import type { GeneratedFile, ShapeContext } from "../create-product.ts";
+import { EXAMPLE_ID } from "./components.ts";
+
+/** The tar ships workflow.yml at its root, so Studio knows the workflow by this name. */
+export const WORKFLOW_NAME = "workflow";
+
+export const DASHBOARD_RUNTIME_SCREEN = {
+  url: `/dashboard/${WORKFLOW_NAME}/`,
+  label: "Open dashboard",
+};
+
+// The starter expose list omits this, which is the whole trap: the dashboard
+// works on the direct Studio port and 404s through the oauth2 proxy.
+export const DASHBOARD_PROXY_EXPOSE = "/dashboard/*";
+
+function packageJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      name: `${ctx.scope}/dashboard`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      description: `Per-workflow operator dashboard. Builds into ../dashboards/${WORKFLOW_NAME}, which the backend packs into the product-template tar and Studio serves at /dashboard/${WORKFLOW_NAME}/.`,
+      scripts: {
+        build: "bunx vite build",
+        dev: "bunx vite build --watch",
+        clean: `rm -rf ../dashboards/${WORKFLOW_NAME}`,
+        typecheck: "bunx tsc --noEmit",
+      },
+      dependencies: {
+        react: "^19.0.0",
+        "react-dom": "^19.0.0",
+      },
+      devDependencies: {
+        "@types/node": "^22.10.0",
+        "@types/react": "^19.0.10",
+        "@types/react-dom": "^19.0.3",
+        "@vitejs/plugin-react": "^6.0.1",
+        typescript: "^5.7.2",
+        vite: "^8.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+// vite.config.ts is deliberately OUT of `include`: it imports vite itself, and
+// the product's `bun run typecheck` should not need the bundler installed to
+// check the app's own sources.
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`;
+
+const VITE_CONFIG_TS = `import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Builds the operator dashboard into ../dashboards/${WORKFLOW_NAME}, which the
+// backend packs into the product-template tar and Studio serves at
+// /dashboard/${WORKFLOW_NAME}/.
+//
+// - \`base: "./"\` — the page is served behind a per-instance proxy prefix
+//   (/instance/<id>/…/dashboard/${WORKFLOW_NAME}/), so an absolute asset URL
+//   escapes the prefix and loads nothing.
+// - the outDir name MUST equal the workflow name. The tar ships workflow.yml at
+//   its root, so the workflow is "${WORKFLOW_NAME}". Get this wrong and
+//   everything still builds, packs and launches — the dashboard just 404s.
+export default defineConfig({
+  base: "./",
+  plugins: [react()],
+  build: {
+    outDir: "../dashboards/${WORKFLOW_NAME}",
+    emptyOutDir: true,
+  },
+});
+`;
+
+function indexHtml(ctx: ShapeContext): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${ctx.name} — Operator</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+}
+
+const API_TS = `// The wire contract with the product's Studio components. The dashboard is a
+// SEPARATE build from components/, so it codes against the HTTP/WS shape rather
+// than importing the component's types.
+//
+// ADDRESSING. The page is served at /instance/<id>/…/dashboard/${WORKFLOW_NAME}/,
+// and it cannot know that prefix at build time. Studio serves an \`env\` document
+// beside it carrying the resolved bases, so everything here is discovered, never
+// hardcoded — a root-absolute "/live/api/…" would resolve against the PROXY ROOT
+// (the norsk-ctl UI) and never reach the instance.
+
+export type Env = { studioUrlPrefix?: string; apiBasePath: string; wsBasePath: string };
+
+// The placeholder component's instance id — the /live/api/<id>/… path segment.
+// Mirrors EXAMPLE_ID in shared/src/workflow/ids.ts; duplicated deliberately,
+// because this is a separate build coding to the wire shape.
+const COMPONENT_ID = "${EXAMPLE_ID}";
+
+/** Relative fetch: resolves against the directory this page is served from. */
+export async function loadEnv(): Promise<Env> {
+  const r = await fetch("env");
+  if (!r.ok) throw new Error(\`env returned HTTP \${r.status}\`);
+  const body = (await r.json()) as Partial<Env>;
+  if (!body.apiBasePath || !body.wsBasePath) throw new Error("env missing apiBasePath/wsBasePath");
+  return body as Env;
+}
+
+export async function apiGet<T>(env: Env, path: string): Promise<T> {
+  const r = await fetch(\`\${env.apiBasePath}/\${COMPONENT_ID}\${path}\`);
+  if (!r.ok) throw new Error(\`GET \${path} -> HTTP \${r.status}\`);
+  return (await r.json()) as T;
+}
+
+export type ExampleState = { ticks: number };
+
+export const getStatus = (env: Env) => apiGet<ExampleState>(env, "/status");
+
+/**
+ * The component's state feed: Studio broadcasts every updates.update() here.
+ *
+ * Studio REFUSES this socket while the component's state is undefined, which is
+ * why the component publishes from its constructor rather than on its first
+ * timer tick.
+ */
+export function openStateSocket(env: Env, onState: (state: ExampleState) => void): WebSocket {
+  const socket = new WebSocket(\`\${env.wsBasePath}/\${COMPONENT_ID}/ws\`);
+  socket.onmessage = (event) => {
+    onState(JSON.parse(event.data as string) as ExampleState);
+  };
+  return socket;
+}
+`;
+
+const APP_TSX = `// PLACEHOLDER operator dashboard — it renders the heartbeat the placeholder
+// component publishes, which is enough to prove the whole path: the tar packed
+// this page, Studio served it, \`env\` resolved the bases, and the component's
+// state socket delivered. Replace the body; keep the shape.
+import { useEffect, useState } from "react";
+import { type Env, type ExampleState, openStateSocket } from "./api.ts";
+
+export default function App({ env }: { env: Env }) {
+  const [state, setState] = useState<ExampleState | undefined>();
+
+  useEffect(() => {
+    const socket = openStateSocket(env, setState);
+    return () => socket.close();
+  }, [env]);
+
+  return (
+    <main>
+      <h1>Operator</h1>
+      <p>
+        Placeholder dashboard — replace it with this product's operator screen, or drop the dashboard workspace if the
+        product does not need one.
+      </p>
+      <p className="tick">
+        {state === undefined ? "waiting for the component's first state…" : \`\${state.ticks} ticks\`}
+      </p>
+    </main>
+  );
+}
+`;
+
+const MAIN_TSX = `import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App.tsx";
+import { loadEnv } from "./api.ts";
+import "./index.css";
+
+// env first, everything else after: the bases every request needs are only
+// knowable at runtime (see api.ts).
+const env = await loadEnv();
+
+const root = document.getElementById("root");
+if (!root) throw new Error("root element missing");
+
+ReactDOM.createRoot(root).render(
+  <React.StrictMode>
+    <App env={env} />
+  </React.StrictMode>,
+);
+`;
+
+const INDEX_CSS = `:root {
+  color-scheme: light dark;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+
+body {
+  margin: 0;
+  padding: 2rem;
+}
+
+.tick {
+  font-variant-numeric: tabular-nums;
+  font-size: 1.5rem;
+}
+`;
+
+const BACKEND_LIB_DASHBOARDS_TS = `// The built dashboard files for the product-template tar. Studio serves them at
+// /dashboard/<workflowName>/ once the template mounts; this backend does not
+// serve them itself. DASHBOARDS_ROOT is the dashboard/ workspace's vite outDir
+// (gitignored build output). The root is ours; the reader is
+// @norskvideo/ctl-sdk's.
+import path from "node:path";
+import { loadDashboardFiles as load } from "@norskvideo/ctl-sdk";
+
+export const DASHBOARDS_ROOT = path.resolve(import.meta.dir, "../../../dashboards");
+
+export const loadDashboardFiles = (root: string = DASHBOARDS_ROOT) => load(root);
+`;
+
+export function dashboardFiles(ctx: ShapeContext): GeneratedFile[] {
+  return [
+    { path: "dashboard/package.json", content: packageJson(ctx) },
+    { path: "dashboard/tsconfig.json", content: TSCONFIG },
+    { path: "dashboard/vite.config.ts", content: VITE_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/api.ts", content: API_TS },
+    { path: "dashboard/src/index.css", content: INDEX_CSS },
+    { path: "backend/src/lib/dashboards.ts", content: BACKEND_LIB_DASHBOARDS_TS },
+  ];
+}
+
+export const DASHBOARD_GITIGNORE = `# Vite output of the dashboard/ workspace (outDir ../dashboards/${WORKFLOW_NAME}).
+# Regenerated by \`bun run build:dashboard\`; packed by the backend at runtime.
+dashboards/
+`;

package/create-product/features/frontend.ts

@@ -0,0 +1,176 @@
+// The `frontend` feature: the product-level configure screen, served by the
+// PRODUCT container at /configure and iframed by ctl at
+// manifest.ui.configScreenUrl.
+//
+// Not to be confused with either operator screen (views.ts, dashboard.ts):
+// those are per-INSTANCE and served by Studio. This one is served once, by the
+// single control-plane container the daemon runs, and its job is to collect the
+// config a product-template is built from.
+//
+// The trap is registration-time. The daemon probes configScreenUrl and refuses
+// the product with CONFIG_SCREEN_UNREACHABLE unless it answers 2xx — which is
+// why declaring it, serving it and building it are one feature rather than
+// 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";
+
+export const CONFIG_SCREEN_URL = "/configure";
+
+function packageJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      name: `${ctx.scope}/frontend`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      scripts: {
+        // Vite's own dev server, for iterating on the screen with HMR. The
+        // BACKEND serves dist/, so this is not what a registered dev product
+        // shows — see the root `dev` script.
+        dev: "bunx vite",
+        build: "bunx vite build",
+        clean: "rm -rf dist",
+        typecheck: "bunx tsc --noEmit",
+      },
+      dependencies: {
+        [`${ctx.scope}/shared`]: "workspace:*",
+        react: "^19.0.0",
+        "react-dom": "^19.0.0",
+      },
+      devDependencies: {
+        "@types/node": "^22.10.0",
+        "@types/react": "^19.0.10",
+        "@types/react-dom": "^19.0.3",
+        "@vitejs/plugin-react": "^6.0.1",
+        typescript: "^5.7.2",
+        vite: "^8.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+// vite.config.ts stays out of `include` — it imports vite itself, and checking
+// the app's own sources should not need the bundler installed.
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`;
+
+const VITE_CONFIG_TS = `import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// \`base: "./"\` — the screen is iframed under the product's own path prefix in
+// the norsk-ctl UI, so absolute asset URLs escape it.
+export default defineConfig({
+  base: "./",
+  plugins: [react()],
+  build: { outDir: "dist", emptyOutDir: true },
+});
+`;
+
+function indexHtml(ctx: ShapeContext): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${ctx.name} — configure</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+}
+
+const MAIN_TSX = `import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App.tsx";
+import "./index.css";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("root element missing");
+
+ReactDOM.createRoot(root).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+`;
+
+function appTsx(ctx: ShapeContext): string {
+  return `// PLACEHOLDER configure screen. The starter template needs no configuration,
+// so this says so rather than pretending to collect something.
+//
+// When the product grows real config: POST the ProductConfig this screen
+// collects to /api/product-template and the backend returns the built tar.
+// ProductConfigSchema (shared/src/schemas/config.ts) is the contract for what
+// belongs here — it is the same schema the route validates against, so this
+// workspace depends on ${ctx.scope}/shared rather than restating the shape.
+export default function App() {
+  return (
+    <main>
+      <h1>${ctx.name}</h1>
+      <p>
+        The starter template needs no configuration. Launch it from norsk-ctl to bring up the Studio + Norsk stack this
+        product composes.
+      </p>
+      <p>
+        Replace this screen when the product grows launch-time config, or drop the frontend workspace if it never does.
+      </p>
+    </main>
+  );
+}
+`;
+}
+
+const INDEX_CSS = `:root {
+  color-scheme: light dark;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+
+body {
+  margin: 0;
+  padding: 2rem;
+}
+`;
+
+export function frontendFiles(ctx: ShapeContext): GeneratedFile[] {
+  return [
+    { path: "frontend/package.json", content: packageJson(ctx) },
+    { path: "frontend/tsconfig.json", content: TSCONFIG },
+    { path: "frontend/vite.config.ts", content: VITE_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/index.css", content: INDEX_CSS },
+  ];
+}
+
+/** The express block serving the built screen at configScreenUrl. */
+export const FRONTEND_SERVER_BLOCK = `  // The configure screen at manifest.ui.configScreenUrl. The daemon probes this
+  // at \`product add\` and refuses the product with CONFIG_SCREEN_UNREACHABLE if
+  // it does not answer 2xx — so it must be BUILT (\`bun run build:frontend\`,
+  // which the image build and the root \`dev\` script both do) before the
+  // product is registered.
+  app.use("${CONFIG_SCREEN_URL}", express.static(FRONTEND_DIST));
+  app.get("${CONFIG_SCREEN_URL}/*splat", (_req, res) => {
+    res.sendFile(path.join(FRONTEND_DIST, "index.html"));
+  });`;

package/create-product/features/views.ts

@@ -0,0 +1,125 @@
+// The `views` feature: the operator screen as React rendered INSIDE Studio's
+// own workflow view — one file per place Studio shows a component: `inline`
+// inside its node on the canvas, `summary` in the sidebar when the node is
+// selected, and a `fullscreen` page at /live/<id>/fullscreen — rather than as a
+// standalone SPA (see dashboard.ts for that answer).
+//
+// It costs no vite workspace and no dashboards/ directory: the screens are
+// compiled into the component's info.client.js by copy-yamls. What it does
+// cost is the browser-bundle constraints — Studio's loader has no import map,
+// so react is rewritten to a window global and nothing here may reach for a
+// bare specifier the loader cannot resolve.
+//
+// State arrives through Studio's own plumbing (ViewProps.state, updated from
+// every updates.update() the runtime publishes) and commands go back through
+// sendCommand, so a view never fetches and never opens a socket.
+import type { GeneratedFile, ShapeContext } from "../create-product.ts";
+
+const INLINE_TSX = `// PLACEHOLDER — rendered INSIDE the component's node on the canvas. Keep it to a
+// line or two: the node is small, and without this view the node shows only its
+// static config. The sidebar is summary.tsx; the full page is fullscreen.tsx.
+//
+// \`state\` is pushed by Studio from the component's updates.update() calls; this
+// file neither fetches nor subscribes.
+import type { ViewProps } from "@norskvideo/norsk-studio/lib/extension/client-types";
+import type { ExampleCommand, ExampleSettings, ExampleState } from "./runtime";
+
+function InlineView({ state }: ViewProps<ExampleSettings, ExampleState, ExampleCommand>) {
+  return (
+    <div className="text-sm text-gray-700 dark:text-gray-300">
+      <span className="font-medium text-gray-900 dark:text-white tabular-nums">{state.ticks}</span> ticks
+    </div>
+  );
+}
+
+export default InlineView;
+`;
+
+const SUMMARY_TSX = `// PLACEHOLDER — rendered in Studio's SIDEBAR when the component's node is
+// selected. More room than the node itself (inline.tsx); the fullscreen view is
+// still where full detail belongs.
+//
+// \`state\` is pushed by Studio from the component's updates.update() calls; this
+// file neither fetches nor subscribes.
+import type { ViewProps } from "@norskvideo/norsk-studio/lib/extension/client-types";
+import type { ExampleCommand, ExampleSettings, ExampleState } from "./runtime";
+
+function SummaryView({ state, config }: ViewProps<ExampleSettings, ExampleState, ExampleCommand>) {
+  return (
+    <dl className="grid grid-cols-2 gap-1 text-sm">
+      <dt className="text-gray-500 dark:text-gray-400">Heartbeats</dt>
+      <dd className="tabular-nums text-gray-900 dark:text-white">{state.ticks}</dd>
+      <dt className="text-gray-500 dark:text-gray-400">Interval</dt>
+      <dd className="tabular-nums text-gray-900 dark:text-white">{config.heartbeatMs ?? 1000} ms</dd>
+    </dl>
+  );
+}
+
+export default SummaryView;
+`;
+
+const FULLSCREEN_TSX = `// PLACEHOLDER — the operator screen, reached at /live/<id>/fullscreen (and via
+// the template manifest's runtimeScreenUrl, which points at Studio). This is
+// where a real product's desk goes: oracle's highlights desk is this file.
+//
+// Two things worth keeping when you replace it:
+//   - state comes from ViewProps and nothing else, so the screen cannot drift
+//     from what the runtime actually published;
+//   - commands go back through sendCommand, which Studio routes to the
+//     component's handleCommand — never through an HTTP call of your own.
+import type { ViewProps } from "@norskvideo/norsk-studio/lib/extension/client-types";
+import type { ExampleCommand, ExampleSettings, ExampleState } from "./runtime";
+
+function FullscreenView({ state, config }: ViewProps<ExampleSettings, ExampleState, ExampleCommand>) {
+  return (
+    <div className="p-6 space-y-4">
+      <header>
+        <h1 className="text-xl font-semibold text-gray-900 dark:text-white">{config.displayName}</h1>
+        <p className="text-sm text-gray-500 dark:text-gray-400">
+          Placeholder operator screen — replace it with this product's desk, or delete it with the component.
+        </p>
+      </header>
+      <dl className="grid grid-cols-2 gap-2 max-w-sm">
+        <dt className="text-gray-500 dark:text-gray-400">Heartbeats</dt>
+        <dd className="tabular-nums text-gray-900 dark:text-white">{state.ticks}</dd>
+        <dt className="text-gray-500 dark:text-gray-400">Interval</dt>
+        <dd className="tabular-nums text-gray-900 dark:text-white">{config.heartbeatMs ?? 1000} ms</dd>
+      </dl>
+    </div>
+  );
+}
+
+export default FullscreenView;
+`;
+
+export function viewsFiles(_ctx: ShapeContext): GeneratedFile[] {
+  return [
+    { path: "components/src/library/example/inline.tsx", content: INLINE_TSX },
+    { path: "components/src/library/example/summary.tsx", content: SUMMARY_TSX },
+    { path: "components/src/library/example/fullscreen.tsx", content: FULLSCREEN_TSX },
+  ];
+}
+
+/** Imports the component's info.ts needs when it registers the three views. Kept
+ *  separate because biome sorts them around the ./runtime import between them. */
+export const VIEWS_INFO_IMPORTS = {
+  fullscreen: 'import FullscreenView from "./fullscreen";',
+  inline: 'import InlineView from "./inline";',
+  summary: 'import SummaryView from "./summary";',
+};
+
+/** The `runtime:` entries registering them. */
+export const VIEWS_INFO_RUNTIME = `      inline: InlineView,
+      summary: SummaryView,
+      fullscreen: FullscreenView,
+`;
+
+// Studio owns the whole per-instance surface here, so the runtime screen IS
+// Studio: ctl anchors studio_url_prefix on its own /studio/ base route and the
+// component's page resolves under it as /instance/<id>/studio/live/<id>/fullscreen.
+export const VIEWS_RUNTIME_SCREEN = { url: "/studio/", label: "Open Studio" };
+
+// /live/api/* covers the component's ROUTES; the per-component PAGES and their
+// state websockets are /live/<id>/fullscreen and /live/<id>/ws, so the wider
+// entry is required or the screen 404s through the proxy while working direct.
+export const VIEWS_PROXY_EXPOSE = "/live/*";