@norskvideo/ctl-dev-kit 0.2.91 → 0.2.93

package/conventions/docs-site.md

@@ -176,12 +176,14 @@ ln -s ../../../../../docs/generated/<slug> website/src/content/docs/guides/<slug
 ```
 
 `docs:site` runs the dev-kit's `docs/guide-stubs.ts stub` first, so the site
-builds on a checkout that has never captured; `publish-docs-site.yml` runs
-`guide-stubs.ts check` after the build and refuses to deploy while any guide
-is still a placeholder. That refusal is deliberate: a product that declares
-recorded guides must also restore (or regenerate) its captures in that
-workflow before the build, and until it does, the publish stops rather than
-shipping an empty page.
+builds on a checkout that has never captured. The captures come from the
+product's nightly `publish-docs.yml`, which saves `docs/generated` to the
+Actions cache after a passing engine tier; `publish-docs-site.yml` restores
+the newest set before its build (and runs when `publish-docs` completes, so a
+fresh capture publishes without waiting for a push). It then runs
+`guide-stubs.ts check` and refuses to deploy while any guide is still a
+placeholder: until the guide has been captured once, the publish stops rather
+than shipping an empty page.
 
 ## The two builds
 
@@ -211,9 +213,10 @@ holds the copy byte-identical, and `bun run sync:drift` writes it — creating i
 where the repo has a site and is not a turnkey. On every push to `main` (and on
 demand) it installs `website/`, builds the public variant and deploys
 `website/dist-public` to Cloudflare Pages with `wrangler`. It never cancels a
-run in flight, because a cancelled deploy is a half-published site. It restores
-no capture cache: a product site builds from the committed prose, so there is
-nothing a nightly run would have that a push does not.
+run in flight, because a cancelled deploy is a half-published site. Before the
+build it restores the newest recorded-guide captures from the Actions cache
+(`docs-captures-*`, saved by `publish-docs.yml`); a site with no recorded
+guides restores nothing it reads, and builds from its committed prose.
 
 Where it may exist is the gate's business (ADR-0012, and the documentation
 plan): a repo with `website/astro.config.mjs` may carry it; a repo without a

package/conventions/publish-docs-site.yml

@@ -4,12 +4,14 @@
 #
 # This is the SITE channel, not the bundle: publish-docs.yml / build-docs.yml
 # regenerate the illustrated manual the product image serves at /docs, nightly,
-# from a licensed Docker run. The site builds from the committed prose alone,
-# needs no licence and no Docker, and so rides every push (conventions/
-# docs-site.md, "Two documentation channels"). A site that also symlinks
-# RECORDED guides (website/src/content/docs/guides/<slug> -> docs/generated/<slug>)
-# builds against a placeholder when the capture is absent, and the gate below
-# refuses to deploy one.
+# from a licensed Docker run. The site needs no licence and no Docker, and so
+# rides every push (conventions/docs-site.md, "Two documentation channels").
+# A site that also symlinks RECORDED guides (website/src/content/docs/guides/
+# <slug> -> docs/generated/<slug>) publishes them from the captures that nightly
+# run saves to the Actions cache: they are restored before the build, which
+# stubs only a guide never captured, and the gate below refuses to deploy a
+# stub. So the site also runs when publish-docs completes, to publish a fresh
+# capture without waiting for the next push.
 #
 # This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
 # (conventions/publish-docs-site.yml) and copied verbatim: there is no per-repo
@@ -40,6 +42,11 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
+  # a fresh capture of the recorded guides (publish-docs.yml saves it)
+  workflow_run:
+    workflows: [publish-docs]
+    types: [completed]
+    branches: [main]
 
 permissions:
   contents: read
@@ -114,6 +121,19 @@ jobs:
         with:
           clean: true
 
+      # The recorded guides' captures, from the product's nightly capture run
+      # (publish-docs.yml saves docs/generated after a passing engine tier):
+      # the newest set, restored where docs:site:public expects it. None yet --
+      # a site that records no guides, or before the first capture -- restores
+      # nothing; the build stubs what is missing and the gate below refuses to
+      # deploy a stub.
+      - name: Restore the recorded guides' captures
+        uses: actions/cache/restore@v4
+        with:
+          path: docs/generated
+          key: docs-captures-${{ github.sha }}
+          restore-keys: docs-captures-
+
       # website/ is a STANDALONE package -- its own bun.lock, outside the root
       # workspaces -- so the repo-root install never covers it, and the build
       # needs both: the root for @norskvideo/ctl-dev-kit (docs:site:public stubs
@@ -145,8 +165,9 @@ jobs:
       # be replaced with "run the doc-guide locally", and nothing else would
       # notice -- the build is green, the links resolve. --content reads the
       # guides the site declares by symlink, so a site that declares none has
-      # nothing to refuse; one that does needs its captures on the runner, and
-      # until the repo restores them this step says which pages are missing.
+      # nothing to refuse; one that does needs its captures, restored above,
+      # and until the nightly run has captured them this step says which pages
+      # are missing.
       - name: Refuse to publish placeholder guides
         run: |
           nix develop .#build --command bash -c '

package/conventions/publish-docs.yml

@@ -318,6 +318,18 @@ jobs:
         if: ${{ steps.engine.outcome == 'success' }}
         run: nix develop .#build --command bun run docs:manual
 
+      # The captures, for the product's own docs site: publish-docs-site.yml
+      # restores the newest set, so its recorded guides publish from this run,
+      # the only one that can make them. Only after a passing engine tier, so a
+      # site never takes a half-captured set over the last good one. Each run
+      # its own key: a cache entry is never overwritten.
+      - name: Cache the guide captures for the docs site
+        if: ${{ steps.engine.outcome == 'success' }}
+        uses: actions/cache/save@v4
+        with:
+          path: docs/generated
+          key: docs-captures-${{ github.sha }}-${{ github.run_id }}
+
       # Said three ways, so a failure is never silent: a warning on the run, a
       # line in its summary, and the cell's detail (the notify job).
       - name: Report the engine tier (not gating)

package/create-product/cli.ts

@@ -5,12 +5,16 @@
 // so the bin runs under bun (the fleet's only runtime).
 import { existsSync, readdirSync } from "node:fs";
 import { parseArgs } from "node:util";
+import { createDashboard } from "../dashboard/create-dashboard.ts";
+import { writeDashboardManifest } from "../dashboard/manifest.ts";
 import { createProduct, type ProductFeature, type ProductShape, type StudioLibrary } from "./create-product.ts";
 
 const SHAPES: ProductShape[] = ["backend-turnkey", "turnkey"];
 
 const USAGE = `Usage:
   ctl-dev-kit create-product --name <name> [options] <dir>
+  ctl-dev-kit create-dashboard --name <name> <dir>   a fleet dashboard norsk-mgr hosts (a live runtime list)
+  ctl-dev-kit dashboard-manifest <src> <dist>   write <dist>/dashboard.json from a fleet dashboard's calls
 
 Options:
   --shape <shape>       Repo shape — a preset over the features below (default: backend-turnkey)
@@ -45,8 +49,18 @@ function fail(message: string): never {
 
 export function main(argv: string[]): void {
   const [command, ...rest] = argv;
+  if (command === "dashboard-manifest") {
+    dashboardManifest(rest);
+    return;
+  }
+  if (command === "create-dashboard") {
+    newDashboard(rest);
+    return;
+  }
   if (command !== "create-product") {
-    fail(`unknown command ${JSON.stringify(command ?? "")} — the only command is create-product.`);
+    fail(
+      `unknown command ${JSON.stringify(command ?? "")} — the commands are create-product, create-dashboard and dashboard-manifest.`,
+    );
   }
   const { values, positionals } = parseArgs({
     args: rest,
@@ -123,3 +137,38 @@ Next steps (also in the generated CLAUDE.md and README):
 if (import.meta.main) {
   main(process.argv.slice(2));
 }
+
+function dashboardManifest(args: string[]): void {
+  const [src, dist] = args;
+  if (!src || !dist) fail("dashboard-manifest needs <src> and <dist>.");
+  const written = writeDashboardManifest(src, dist);
+  if (written.status === "error") {
+    console.error(
+      `dashboard.json not written: the build cannot read what this dashboard uses.\n  ${written.error.join("\n  ")}`,
+    );
+    process.exit(1);
+  }
+  const kinds = written.value.kinds;
+  console.log(`${dist}/dashboard.json: uses ${kinds.length > 0 ? kinds.join(", ") : "no kinds"}`);
+}
+
+function newDashboard(args: string[]): void {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { name: { type: "string" } } });
+  const dir = positionals[0];
+  if (!dir) fail("missing <dir>.");
+  if (!values.name) fail("missing --name.");
+  if (existsSync(dir) && readdirSync(dir).length > 0) fail(`${dir} exists and is not empty — refusing to overwrite.`);
+  let files: string[];
+  try {
+    ({ files } = createDashboard({ dir, name: values.name }));
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  console.log(`Generated ${files.length} files into ${dir}.
+
+Next steps (also in its README):
+  1. cd ${dir} && bun install
+  2. bun run build                     # dist/dashboard.json and dashboard.tar
+  3. norsk-mgr dashboard register ${values.name} && norsk-mgr dashboard upload ${values.name} dashboard.tar
+`);
+}

package/dashboard/create-dashboard.ts

@@ -0,0 +1,198 @@
+// `ctl-dev-kit create-dashboard --name <name> <dir>` (task 122 K): a fleet
+// dashboard, a static bundle norsk-mgr hosts on a host of its own, a shared
+// one or a pattern's (RFC 0006 §4.4). The starter is a live list of the
+// runtimes the signed-in user may see, the smallest real consumer of the
+// directory.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+export interface CreateDashboardOptions {
+  dir: string;
+  /** The dashboard's name: its registration's, and its host's when it has
+   *  one of its own. */
+  name: string;
+}
+
+function files(name: string): Record<string, string> {
+  return {
+    "package.json": `${JSON.stringify(
+      {
+        name,
+        private: true,
+        type: "module",
+        scripts: {
+          dev: "vite",
+          build: "vite build && ctl-dev-kit dashboard-manifest src dist && tar -C dist -cf dashboard.tar .",
+          typecheck: "tsc --noEmit",
+        },
+        dependencies: { "@norskvideo/ctl-sdk": "^0.1.1" },
+        devDependencies: { "@norskvideo/ctl-dev-kit": "^0.2.0", typescript: "^5.9.0", vite: "^8.0.0" },
+      },
+      null,
+      2,
+    )}\n`,
+    "tsconfig.json": `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          lib: ["ES2022", "DOM"],
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ["src", "vite.config.ts"],
+      },
+      null,
+      2,
+    )}\n`,
+    ".gitignore": "node_modules/\ndist/\ndashboard.tar\n",
+    "index.html": `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <h1>Runtimes</h1>
+    <p id="status">Connecting…</p>
+    <table>
+      <thead>
+        <tr><th>Runtime</th><th>Production or product</th><th>State</th><th>Node</th></tr>
+      </thead>
+      <tbody id="runtimes"></tbody>
+    </table>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>
+`,
+    "src/main.ts": `// The runtimes the signed-in user may see, live. The platform decides who
+// sees what; this page only shows it.
+//
+// Name the kinds a fleet call reads with literals: \`bun run build\` derives
+// dashboard.json, the registration's list of what this dashboard uses, from
+// them, and norsk-mgr serves it no wider than that list.
+import { type FleetItem, fleet } from "@norskvideo/ctl-sdk/fleet";
+
+const rows = document.getElementById("runtimes") as HTMLTableSectionElement;
+const status = document.getElementById("status") as HTMLParagraphElement;
+
+function cell(text: string): HTMLTableCellElement {
+  const td = document.createElement("td");
+  td.textContent = text;
+  return td;
+}
+
+function render(items: FleetItem[]): void {
+  rows.replaceChildren(
+    ...items.map((item) => {
+      const tr = document.createElement("tr");
+      const { runtime } = item;
+      tr.append(
+        cell(String(runtime.name ?? runtime.id)),
+        cell(String(runtime.production ?? runtime.product ?? "")),
+        cell(item.presence?.labels["norsk.state"] ?? "unknown"),
+        cell(String(runtime.node ?? "")),
+      );
+      return tr;
+    }),
+  );
+  status.textContent = items.length === 0 ? "No runtimes you may see." : \`\${items.length} runtime(s)\`;
+}
+
+fleet.watch(
+  { kind: "norsk.runtime" },
+  {
+    onChange: render,
+    onError: () => {
+      status.textContent = "Reconnecting…";
+    },
+  },
+);
+`,
+    "vite.config.ts": `import { defineConfig } from "vite";
+
+// Relative URLs throughout: a shared host serves this dashboard under
+// /<name>/, its own host at the root.
+//
+// \`bun run dev\` reads a directory elsewhere at the page's own /_fleet, as a
+// dashboard host serves it: NORSK_DIRECTORY_URL is norsk-mgr's or norsk-ctl's
+// base URL, and NORSK_TOKEN an API token for it.
+const target = process.env.NORSK_DIRECTORY_URL;
+const token = process.env.NORSK_TOKEN;
+
+export default defineConfig({
+  base: "./",
+  server: target
+    ? {
+        proxy: {
+          "/_fleet": {
+            target,
+            changeOrigin: true,
+            secure: false,
+            rewrite: (path) => path.replace(/^\\/_fleet/, "/api/v1/fleet"),
+            ...(token ? { headers: { authorization: \`Bearer \${token}\` } } : {}),
+          },
+        },
+      }
+    : {},
+});
+`,
+    "README.md": `# ${name}
+
+A fleet dashboard: a static bundle norsk-mgr serves on a host of its own, reading
+the directory (the runtimes the signed-in user may see, with what discovery
+holds under each) through \`@norskvideo/ctl-sdk/fleet\`.
+
+## Develop
+
+\`\`\`sh
+bun install
+NORSK_DIRECTORY_URL=https://mgr.example.com NORSK_TOKEN=<an API token> bun run dev
+\`\`\`
+
+The dev server reads that norsk-mgr's (or norsk-ctl's) directory as the token's
+holder sees it, at the page's own \`/_fleet\`, as the dashboard host will.
+
+## Build and register
+
+\`\`\`sh
+bun run build                       # dist/, dist/dashboard.json and dashboard.tar
+norsk-mgr dashboard register ${name}  # a host of its own: ${name}.<productUiDomain>
+norsk-mgr dashboard upload ${name} dashboard.tar
+\`\`\`
+
+\`--hosting shared:<group>\` serves it under \`/${name}/\` on its group's host instead;
+\`--hosting pattern:<prefix>-{id} --scope production\` on a host per production,
+each answering only for its own. Uploading again replaces the bundle in place.
+
+## What it may read
+
+\`dashboard.json\` lists the kinds the dashboard's fleet calls name, and the build
+derives it: name kinds as literals (\`fleet.watch({ kind: "norsk.runtime" })\`), or
+the build fails. The dashboard host answers no wider than that list.
+`,
+  };
+}
+
+export function createDashboard(opts: CreateDashboardOptions): { files: string[] } {
+  if (!LABEL.test(opts.name) || opts.name.length > 63) {
+    throw new Error(
+      `the name \${JSON.stringify(opts.name)} must be one DNS label: lowercase letters, digits and '-', at most 63`,
+    );
+  }
+  if (opts.name.startsWith("t-") || opts.name.startsWith("p-")) {
+    throw new Error(`the name \${JSON.stringify(opts.name)} starts with t- or p-, which product UI hosts use`);
+  }
+  const out = files(opts.name);
+  for (const [path, content] of Object.entries(out)) {
+    mkdirSync(dirname(join(opts.dir, path)), { recursive: true });
+    writeFileSync(join(opts.dir, path), content);
+  }
+  return { files: Object.keys(out) };
+}

package/dashboard/manifest.ts

@@ -0,0 +1,30 @@
+// `ctl-dev-kit dashboard-manifest <src> <dist>`: a fleet dashboard's build
+// step (task 122 K). Writes `<dist>/dashboard.json`, which norsk-mgr reads at
+// upload for what the dashboard uses, from the calls in `<src>`.
+
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { dashboardUses, type UsesResult } from "./uses.ts";
+
+const SOURCE = /\.(m?[jt]sx?)$/;
+const TEST = /\.(test|spec)\.[^.]+$/;
+
+function sources(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules") continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...sources(full));
+    else if (SOURCE.test(name) && !TEST.test(name)) out.push(full);
+  }
+  return out;
+}
+
+export function writeDashboardManifest(srcDir: string, distDir: string): UsesResult {
+  const files = sources(srcDir).map((path) => ({ path: relative(srcDir, path), source: readFileSync(path, "utf8") }));
+  const uses = dashboardUses(files);
+  if (uses.status === "error") return uses;
+  mkdirSync(distDir, { recursive: true });
+  writeFileSync(join(distDir, "dashboard.json"), `${JSON.stringify({ uses: uses.value }, null, 2)}\n`);
+  return uses;
+}

package/dashboard/uses.ts

@@ -0,0 +1,115 @@
+// What a fleet dashboard uses, derived from its own code when it is built
+// (RFC 0006 registration-names-what-it-uses, task 122 K): every kind its
+// `fleet.query` and `fleet.watch` calls name, read as literals. A call the
+// build cannot read, or any other use of the client, fails the build rather
+// than leave `dashboard.json` short of what the code reads.
+
+import ts from "typescript";
+
+export const FLEET_MODULE = "@norskvideo/ctl-sdk/fleet";
+const CALLS = new Set(["query", "watch"]);
+
+export interface DashboardUses {
+  kinds: string[];
+}
+
+export type UsesResult = { status: "ok"; value: DashboardUses } | { status: "error"; error: string[] };
+
+function literalKinds(node: ts.Expression): string[] | undefined {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return [node.text];
+  if (!ts.isArrayLiteralExpression(node)) return undefined;
+  const kinds: string[] = [];
+  for (const element of node.elements) {
+    if (!ts.isStringLiteral(element) && !ts.isNoSubstitutionTemplateLiteral(element)) return undefined;
+    kinds.push(element.text);
+  }
+  return kinds;
+}
+
+function kindsOfSelection(arg: ts.Expression | undefined): string[] | undefined {
+  if (arg === undefined || !ts.isObjectLiteralExpression(arg)) return undefined;
+  for (const property of arg.properties) {
+    if (ts.isPropertyAssignment(property) && property.name.getText() === "kind") {
+      return literalKinds(property.initializer);
+    }
+  }
+  return undefined;
+}
+
+export function dashboardUses(files: readonly { path: string; source: string }[]): UsesResult {
+  const kinds = new Set<string>();
+  const problems: string[] = [];
+  for (const { path, source } of files) {
+    const sf = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true);
+    const where = (node: ts.Node) => `${path}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;
+    // The names the module's client is bound to here: the `fleet` export, and
+    // consts holding a `fleetClient(...)`.
+    const clients = new Set<string>();
+    const factories = new Set<string>();
+    for (const statement of sf.statements) {
+      if (!ts.isImportDeclaration(statement)) continue;
+      if (!ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== FLEET_MODULE) continue;
+      const named = statement.importClause?.namedBindings;
+      if (named === undefined) continue;
+      if (ts.isNamespaceImport(named)) {
+        problems.push(
+          `${where(named)}: import the fleet client by name (\`import { fleet }\`), so its calls can be read`,
+        );
+        continue;
+      }
+      for (const element of named.elements) {
+        const imported = (element.propertyName ?? element.name).text;
+        if (imported === "fleet") clients.add(element.name.text);
+        if (imported === "fleetClient") factories.add(element.name.text);
+      }
+    }
+    if (clients.size === 0 && factories.size === 0) continue;
+
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.initializer !== undefined &&
+        ts.isCallExpression(node.initializer) &&
+        ts.isIdentifier(node.initializer.expression) &&
+        factories.has(node.initializer.expression.text)
+      ) {
+        clients.add(node.name.text);
+        for (const arg of node.initializer.arguments) visit(arg);
+        return;
+      }
+      if (
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        clients.has(node.expression.expression.text) &&
+        CALLS.has(node.expression.name.text)
+      ) {
+        const found = kindsOfSelection(node.arguments[0]);
+        if (found === undefined) {
+          problems.push(
+            `${where(node)}: ${node.expression.getText()} must name its kind as a literal, or a list of literals, in the selection it is passed, so the dashboard's uses can be derived`,
+          );
+        } else {
+          for (const kind of found) kinds.add(kind);
+        }
+        for (const arg of node.arguments) visit(arg);
+        return;
+      }
+      if (ts.isIdentifier(node) && (clients.has(node.text) || factories.has(node.text))) {
+        const parent = node.parent;
+        const declaring = ts.isImportSpecifier(parent) || (ts.isVariableDeclaration(parent) && parent.name === node);
+        if (!declaring) {
+          problems.push(
+            `${where(node)}: ${node.text} is used other than by calling its query or watch, so the build cannot see what it reads`,
+          );
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+  }
+  return problems.length > 0
+    ? { status: "error", error: problems }
+    : { status: "ok", value: { kinds: [...kinds].sort() } };
+}

package/package.json

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