@norskvideo/ctl-dev-kit 0.2.2 → 0.2.4

package/docs-theme/starlight.ts

@@ -0,0 +1,162 @@
+/**
+ * The Astro + Starlight configuration every Norsk product docs site is built
+ * from. A site's own `astro.config.mjs` is reduced to what genuinely differs:
+ * its origin, its two names, its sidebar, and the versions it was built
+ * against.
+ *
+ *     export default defineConfig(
+ *       norskDocsSite({
+ *         origin: PUBLIC_SITE_ORIGIN,
+ *         tabTitle: "Norsk",
+ *         wordmark: "norsk-ctl",
+ *         buildVersions: [...],
+ *         sidebar: [...],
+ *       }),
+ *     );
+ *
+ * Everything here is the part that must NOT differ between sites: the theme,
+ * the component overrides, the mermaid pipeline, the favicon convention, and
+ * the two-build (public / embedded) shape described on `publicBuild` below.
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { unified } from "@astrojs/markdown-remark";
+import starlight from "@astrojs/starlight";
+import rehypeMermaid from "rehype-mermaid";
+
+/** One row of the sidebar's "Built against" footer (components/Sidebar.astro). */
+export interface BuildVersion {
+  /** Row label, e.g. "norsk-ctl". */
+  label: string;
+  /** Row value, read at build time from the product's own files. */
+  value: string;
+  /** Break a `repo:tag` image pin after the last colon so it wraps sensibly. */
+  splitOnLastColon?: boolean;
+}
+
+export interface NorskDocsSiteOptions {
+  /** Canonical public origin. Drives the sitemap and <link rel="canonical">. */
+  origin: string;
+  /** BROWSER TAB suffix only ("Quickstart | Norsk"), kept short — tabs truncate. */
+  tabTitle: string;
+  /** Masthead wordmark. Deliberately different from `tabTitle`; see SiteTitle.astro. */
+  wordmark: string;
+  /** Starlight's sidebar. The one part of the nav a site fully owns. */
+  sidebar: unknown[];
+  /** Rows for the sidebar's "Built against" footer. */
+  buildVersions: BuildVersion[];
+  /**
+   * Dev-preview only: machine names `astro dev --host` may be reached by on the
+   * LAN (Vite 403s unknown Host headers otherwise). No effect on builds.
+   */
+  devAllowedHosts?: string[];
+}
+
+/**
+ * Two builds from one content collection, selected by ASTRO_BUILD:
+ * `dist-embedded` (base `/docs`) is the bundle baked into a product binary and
+ * served by the daemon, `dist-public` (base `/`) is the standalone site on the
+ * product's own domain. Exported because a site's sidebar legitimately differs
+ * between the two — a section that only exists once it is published.
+ */
+export function isPublicBuild(): boolean {
+  return process.env.ASTRO_BUILD === "public";
+}
+
+/**
+ * Content (and any vendored HTML) is authored with absolute /docs/... links —
+ * correct for the daemon-embedded build (served under /docs), but a 404 in the
+ * public build (served at /). Astro doesn't base-prefix absolute links in
+ * MDX/components/static files, so for the public build a post-build pass strips
+ * the /docs prefix from href/src attributes across the emitted HTML.
+ * Attribute-scoped so it never touches /docs literals in body text. No-op for
+ * the embedded build.
+ */
+function stripDocsBaseForPublic() {
+  const rewriteHtml = (html: string) =>
+    html.replace(/((?:href|src)=")\/docs(\/|")/g, (_m, attr, tail) => (tail === "/" ? `${attr}/` : `${attr}/"`));
+  const walk = (root: string, fn: (p: string) => void) => {
+    for (const name of readdirSync(root)) {
+      const p = join(root, name);
+      if (statSync(p).isDirectory()) walk(p, fn);
+      else if (p.endsWith(".html")) fn(p);
+    }
+  };
+  return {
+    name: "strip-docs-base-public",
+    hooks: {
+      "astro:build:done": ({ dir }: { dir: URL }) => {
+        if (!isPublicBuild()) return;
+        walk(fileURLToPath(dir), (p) => {
+          writeFileSync(p, rewriteHtml(readFileSync(p, "utf-8")));
+        });
+      },
+    },
+  };
+}
+
+export function norskDocsSite(options: NorskDocsSiteOptions) {
+  const isPublic = isPublicBuild();
+  const mermaidLaunchOptions = process.env.BROWSER_FOR_TESTING
+    ? { executablePath: process.env.BROWSER_FOR_TESTING }
+    : undefined;
+
+  return {
+    // The public site lives at the domain root; the embedded bundle is served
+    // by the daemon under /docs. `site` is the canonical origin: it drives the
+    // sitemap and <link rel="canonical">, and without it @astrojs/sitemap
+    // (pulled in by Starlight) skips and warns. The embedded build reuses the
+    // same origin — its sitemap is inert since it is never crawled, but setting
+    // `site` keeps the build warning-free.
+    site: options.origin,
+    base: isPublic ? "/" : "/docs",
+    outDir: isPublic ? "./dist-public" : "./dist-embedded",
+    markdown: {
+      syntaxHighlight: { excludeLangs: ["mermaid"] },
+      // Astro 6 deprecated top-level `rehypePlugins`; the pipeline now lives in
+      // a `unified()` processor. `syntaxHighlight` stays at the markdown level.
+      processor: unified({
+        rehypePlugins: [
+          [
+            rehypeMermaid,
+            { strategy: "img-svg", dark: true, mermaidConfig: { theme: "dark" }, launchOptions: mermaidLaunchOptions },
+          ],
+        ],
+      }),
+    },
+    integrations: [
+      stripDocsBaseForPublic(),
+      starlight({
+        title: options.tabTitle,
+        customCss: ["./src/custom.css"],
+        components: {
+          // Appends the "Built against" footer below the nav.
+          Sidebar: "./src/components/Sidebar.astro",
+          // Decouples the masthead wordmark from `title` above.
+          SiteTitle: "./src/components/SiteTitle.astro",
+          // Adds the "captured against" line to a generated guide (front
+          // matter `capturedAgainst`, see content.config.ts).
+          Footer: "./src/components/Footer.astro",
+        },
+        // Starlight base-prefixes this (emits a `/docs/favicon.png`
+        // shortcut-icon link for the embedded build); a raw head <link> would
+        // not, and 404s the embedded link-check.
+        favicon: "/favicon.png",
+        sidebar: options.sidebar,
+      }),
+    ],
+    vite: {
+      server: { allowedHosts: options.devAllowedHosts ?? [] },
+      // Injected rather than imported: a component resolving its own path at
+      // runtime finds dist-embedded/.prerender/chunks/ instead of the source
+      // tree and fails the build, and the site's version readers want the
+      // product's files, not the site's. Both values are build-time constants,
+      // so a define is the cheapest correct channel.
+      define: {
+        __BUILD_VERSIONS__: JSON.stringify(options.buildVersions),
+        __SITE_WORDMARK__: JSON.stringify(options.wordmark),
+      },
+    },
+  };
+}

package/docs-theme/sync.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env bun
+/**
+ * The docs theme is a FORCED COPY, and this is its writer and its gate.
+ *
+ *   sync.ts check <site>   diff the site's copies against this dev-kit's
+ *                          canonical bytes; exit 1 on drift, naming the file.
+ *   sync.ts sync  <site>   rewrite the copies from the canonical.
+ *
+ * `<site>` is the docs site's package root (the directory holding
+ * `astro.config.mjs`); it defaults to the current directory.
+ *
+ * WHY A COPY, when the dev-kit's rule is to single-source anything consumable.
+ * A docs site is a STANDALONE package: it carries its own bun.lock and its own
+ * node_modules, outside the monorepo's workspaces, because Astro's dependency
+ * tree has no business in the product install. So it cannot depend on the
+ * dev-kit the way every other consumer does. That is not a preference — it is
+ * checked: adding `"@norskvideo/ctl-dev-kit": "file:../../dev-kit"` to
+ * norsk-ctl's website and installing fails outright, because bun then has to
+ * resolve the dev-kit's own `workspace:*` dependencies (ctl-sdk, foundation,
+ * test-harness, product-template-schema) from a directory that is not in a
+ * workspace:
+ *
+ *     error: @norskvideo/ctl-sdk@workspace:* failed to resolve
+ *
+ * A product repo outside this monorepo installs the published tarball and hits
+ * no such wall — but it would then consume the theme by a second mechanism, and
+ * one theme reaching two sites two ways is exactly the drift this package
+ * exists to stop. So every site, here and elsewhere, gets the same deal: copies
+ * at fixed paths, rewritten by `sync`, and `check` in its test suite.
+ *
+ * The copies land at the paths Starlight and Astro already expect
+ * (`src/custom.css`, `src/components/*.astro`, `src/content.config.ts`), which
+ * is also why the canonical directory mirrors a site's own tree: the map below
+ * is an identity. Keeping the component paths identical is load-bearing for
+ * more than tidiness — Astro derives a component's scoped-style class from its
+ * path, so moving one rewrites a class attribute on every page.
+ *
+ * One canonical subdirectory is NOT under `src/`: `public/` mirrors the site's
+ * `public/`, because `starlight.ts` already names the favicon
+ * (`favicon: "/favicon.png"`) and a path the theme dictates whose bytes each
+ * site supplies for itself is half a convention. Both sites' copies were
+ * byte-identical when it moved here, so the gate gained a file rather than the
+ * sites gaining a difference.
+ *
+ * Canonical bytes are resolved relative to THIS file, so the script works both
+ * workspace-symlinked and installed from the published tarball — the same
+ * arrangement as conventions/check-drift.ts.
+ */
+import { cpSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CANONICAL = dirname(fileURLToPath(import.meta.url));
+
+/** The site subdirectory the canonical tree is copied into. */
+export const SITE_DIR = "src";
+
+/** The one canonical subdirectory that mirrors the site's root, not its `src/`
+ *  — Astro serves `public/` verbatim, and `starlight.ts` names `/favicon.png`. */
+export const PUBLIC_DIR = "public";
+
+/** Where a canonical file lands in a site, relative to the site root. */
+export function sitePath(rel: string): string {
+  return rel === PUBLIC_DIR || rel.startsWith(`${PUBLIC_DIR}/`) ? rel : join(SITE_DIR, rel);
+}
+
+/**
+ * Every canonical file, as a path relative to this directory — which is also
+ * its path relative to the site's `src/` ({@link sitePath}, bar `public/`).
+ * Derived from the tree rather than listed, so a file added here reaches every
+ * site without a second edit; the script's own source and its test are the only
+ * exclusions.
+ */
+export function themeFiles(canonical: string = CANONICAL): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir).sort()) {
+      const p = join(dir, name);
+      if (statSync(p).isDirectory()) {
+        walk(p);
+        continue;
+      }
+      const rel = relative(canonical, p);
+      if (rel === "sync.ts" || rel === "sync.test.ts" || rel === "README.md") continue;
+      out.push(rel);
+    }
+  };
+  walk(canonical);
+  return out;
+}
+
+export interface ThemeDrift {
+  ok: boolean;
+  problems: string[];
+}
+
+const RESYNC = "Edit the dev-kit source and re-run `sync`, never hand-edit the copy.";
+
+/** Compare a site's copies against the canonical bytes. Text is diffed by line
+ *  so the failure names the drift; binaries (the woff2) compare byte-wise. */
+export function checkTheme(siteRoot: string, canonical: string = CANONICAL): ThemeDrift {
+  const problems: string[] = [];
+  for (const rel of themeFiles(canonical)) {
+    const at = sitePath(rel);
+    const want = readFileSync(join(canonical, rel));
+    let got: Buffer;
+    try {
+      got = readFileSync(join(siteRoot, at));
+    } catch {
+      problems.push(`${at}: missing — the docs theme is not synced. ${RESYNC}`);
+      continue;
+    }
+    if (got.equals(want)) continue;
+    problems.push(`${at}: ${firstDiff(got, want)}. ${RESYNC}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+function firstDiff(got: Buffer, want: Buffer): string {
+  // A woff2 has no lines worth naming; say so rather than printing binary.
+  if (got.includes(0) || want.includes(0))
+    return `differs from the canonical (${want.length} bytes, found ${got.length})`;
+  const a = got.toString("utf8").split("\n");
+  const e = want.toString("utf8").split("\n");
+  for (let i = 0; i < Math.max(a.length, e.length); i++) {
+    if (a[i] !== e[i]) {
+      return `line ${i + 1}: expected ${JSON.stringify(e[i] ?? "<missing>")}, found ${JSON.stringify(a[i] ?? "<missing>")}`;
+    }
+  }
+  return "content differs";
+}
+
+/** Rewrite the site's copies from the canonical bytes. */
+export function syncTheme(siteRoot: string, canonical: string = CANONICAL): string[] {
+  const written: string[] = [];
+  for (const rel of themeFiles(canonical)) {
+    const at = sitePath(rel);
+    const to = join(siteRoot, at);
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(join(canonical, rel), to);
+    written.push(at);
+  }
+  return written;
+}
+
+if (import.meta.main) {
+  const [mode, site] = process.argv.slice(2);
+  const siteRoot = site ?? process.cwd();
+  if (mode === "sync") {
+    for (const f of syncTheme(siteRoot)) console.log(`wrote ${f}`);
+  } else if (mode === "check") {
+    const { ok, problems } = checkTheme(siteRoot);
+    if (!ok) {
+      console.error("docs theme drift:");
+      for (const p of problems) console.error(`  - ${p}`);
+      process.exit(1);
+    }
+    console.log(`docs theme: ${themeFiles().length} files in step with the dev-kit.`);
+  } else {
+    console.error("usage: sync.ts check|sync [site-root]");
+    process.exit(2);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
@@ -12,6 +12,7 @@
     "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.js",
     "./doc-guide/live-browser": "./doc-guide/live-browser.js",
     "./doc-guide/prose-bundle": "./doc-guide/prose-bundle.js",
+    "./docs-theme/sync": "./docs-theme/sync.ts",
     "./docs/path-existence": "./docs/path-existence.ts",
     "./docs/splice-generated": "./docs/splice-generated.ts",
     "./licence/check-entitlement": "./licence/check-entitlement.ts",