@norskvideo/ctl-dev-kit 0.2.54 → 0.2.55

package/docs/journeys.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env bun
+// The journey-table lint (documentation plan, October 2026, "Who we write for").
+// Each product's docs/personas.md carries one table saying where each of the
+// four readers starts, which pages they read in order, and where they are
+// handed off — ctl's manual for the Administrator and the Integrator. The
+// table is the product's statement of its journeys; this checks that it exists,
+// covers every persona once, keeps each route to five pages, names only pages
+// that exist, and always ends in a hand-off. A site path `/docs/x/` resolves to
+// website/src/content/docs/x.{md,mdx} or x/index.{md,mdx}; a bare `name.md`
+// resolves under docs/; an https link is a hand-off and is not resolved.
+//
+// Usage: bun journeys.ts [--root <dir>] [--personas docs/personas.md]
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const PERSONAS = ["Evaluator", "Builder", "Integrator", "Administrator"] as const;
+export const MAX_PAGES = 5;
+
+export interface JourneyRow {
+  persona: string;
+  startsAt: string[];
+  next: string[];
+  handsOffTo: string;
+  /** 1-based line of the row in the personas file. */
+  line: number;
+}
+
+export interface JourneyTable {
+  rows: JourneyRow[];
+  /** 1-based line of the header row. */
+  line: number;
+}
+
+export interface JourneyFinding {
+  file: string;
+  line: number;
+  message: string;
+}
+
+const CELL_PATH = /`([^`]+)`|\]\(([^)]+)\)|(^|\s)(\/docs\/\S*|\S+\.mdx?)(?=\s|,|$)/g;
+
+/** Every path-like reference in a table cell: backticked, a markdown link
+ *  target, or a bare `/docs/...` or `*.md` token. */
+export function cellPaths(cell: string): string[] {
+  const out: string[] = [];
+  for (const m of cell.matchAll(CELL_PATH)) {
+    const p = (m[1] ?? m[2] ?? m[4] ?? "").trim();
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+/** A persona cell may be bold or a link to its section; the name is the text. */
+function plainText(cell: string): string {
+  return cell
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`]/g, "")
+    .trim();
+}
+
+function splitRow(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((c) => c.trim());
+}
+
+export function parseJourneyTable(markdown: string): JourneyTable | undefined {
+  const lines = markdown.split("\n");
+  for (let i = 0; i < lines.length - 1; i++) {
+    const line = lines[i] ?? "";
+    if (!line.trim().startsWith("|")) continue;
+    const header = splitRow(line).map((c) => c.toLowerCase());
+    const col = (want: string) => header.findIndex((h) => h.startsWith(want));
+    const persona = col("persona");
+    const startsAt = col("starts at");
+    const then = col("then");
+    const handsOff = col("hands off");
+    if (persona < 0 || startsAt < 0 || then < 0 || handsOff < 0) continue;
+    if (!/^\s*\|?\s*:?-+/.test(lines[i + 1] ?? "")) continue;
+    const rows: JourneyRow[] = [];
+    for (let j = i + 2; j < lines.length; j++) {
+      const row = lines[j] ?? "";
+      if (!row.trim().startsWith("|")) break;
+      const cells = splitRow(row);
+      rows.push({
+        persona: plainText(cells[persona] ?? ""),
+        startsAt: cellPaths(cells[startsAt] ?? ""),
+        next: cellPaths(cells[then] ?? ""),
+        handsOffTo: cells[handsOff] ?? "",
+        line: j + 1,
+      });
+    }
+    return { rows, line: i + 1 };
+  }
+  return undefined;
+}
+
+const SITE_DOCS = "website/src/content/docs";
+
+function hasReaders(root: string): boolean {
+  return (
+    existsSync(join(root, SITE_DOCS)) ||
+    existsSync(join(root, "website", "astro.config.mjs")) ||
+    existsSync(join(root, "docs", "quickstart.md"))
+  );
+}
+
+/** Where a route's page lives in the repo, or undefined for a link that is a
+ *  hand-off rather than a page (https, mailto). */
+export function candidatePaths(ref: string): string[] | undefined {
+  const bare = ref.replace(/[#?].*$/, "");
+  if (/^[a-z]+:/i.test(bare)) return undefined;
+  if (bare.startsWith("/docs/") || bare === "/docs") {
+    const rel = bare.replace(/^\/docs\/?/, "").replace(/\/$/, "");
+    const base = rel === "" ? "index" : rel;
+    return [
+      `${SITE_DOCS}/${base}.mdx`,
+      `${SITE_DOCS}/${base}.md`,
+      `${SITE_DOCS}/${base}/index.mdx`,
+      `${SITE_DOCS}/${base}/index.md`,
+    ];
+  }
+  if (bare.startsWith("docs/")) return [bare];
+  return [`docs/${bare}`, bare];
+}
+
+export function checkJourneys(root: string, personasFile = "docs/personas.md"): JourneyFinding[] {
+  const file = join(root, personasFile);
+  if (!existsSync(file)) {
+    // A repo with no site and no quickstart has no readers to route: a
+    // backend-only turnkey ships a handover to one customer and is not asked
+    // for four journeys. Anything with a Start here page is.
+    if (!hasReaders(root)) return [];
+    return [
+      {
+        file: personasFile,
+        line: 1,
+        message: "missing; every product keeps its persona mapping and journey table here (conventions/personas.md).",
+      },
+    ];
+  }
+  const table = parseJourneyTable(readFileSync(file, "utf8"));
+  if (!table) {
+    return [
+      {
+        file: personasFile,
+        line: 1,
+        message:
+          'no journey table: expected a table with columns Persona | Starts at | Then, in order | Hands off to (documentation plan, "Who we write for").',
+      },
+    ];
+  }
+  const findings: JourneyFinding[] = [];
+  const seen = new Map<string, number>();
+  for (const row of table.rows) {
+    seen.set(row.persona, (seen.get(row.persona) ?? 0) + 1);
+    const pages = [...row.startsAt, ...row.next];
+    if (pages.length > MAX_PAGES) {
+      findings.push({
+        file: personasFile,
+        line: row.line,
+        message: `${row.persona}: ${pages.length} pages on the route; the limit is ${MAX_PAGES}. A sixth page is in the wrong section or should not exist.`,
+      });
+    }
+    for (const ref of pages) {
+      const candidates = candidatePaths(ref);
+      if (!candidates) continue;
+      if (!candidates.some((c) => existsSync(join(root, c)))) {
+        findings.push({
+          file: personasFile,
+          line: row.line,
+          message: `${row.persona}: ${ref} is not a page in this repo (looked for ${candidates.join(", ")}).`,
+        });
+      }
+    }
+    if (!/\S/.test(row.handsOffTo) || cellPaths(row.handsOffTo).length === 0) {
+      findings.push({
+        file: personasFile,
+        line: row.line,
+        message: `${row.persona}: no hand-off. Every route ends in a link: the next section, or norsk-ctl's manual.`,
+      });
+    }
+  }
+  for (const persona of PERSONAS) {
+    const n = seen.get(persona) ?? 0;
+    if (n === 0)
+      findings.push({ file: personasFile, line: table.line, message: `${persona} has no row in the journey table.` });
+    else if (n > 1)
+      findings.push({
+        file: personasFile,
+        line: table.line,
+        message: `${persona} has ${n} rows in the journey table; one route each.`,
+      });
+  }
+  return findings;
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  let root = process.cwd();
+  let personas = "docs/personas.md";
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--root") root = argv[++i] ?? root;
+    else if (argv[i] === "--personas") personas = argv[++i] ?? personas;
+  }
+  const findings = checkJourneys(root, personas);
+  if (findings.length === 0) {
+    console.log("journeys: OK");
+  } else {
+    console.error(`journeys: ${findings.length} finding${findings.length === 1 ? "" : "s"}`);
+    for (const f of findings) console.error(`  - ${f.file}:${f.line}: ${f.message}`);
+    process.exit(1);
+  }
+}

package/docs/light-pages.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env bun
+// The "light pages" lint (documentation plan, October 2026, "Keeping it light").
+// A product's Start here and Guides pages are written for the Evaluator and the
+// Builder, who do not know our engineering vocabulary and should not need to;
+// the rule in conventions/docs.md ("Voice") bans those words but had no scope
+// and no gate, so it was broken by the very indexes that cite it. This gives it
+// a scope — the light half of a site, and a repo's docs/quickstart.md — and a
+// gate: a word from the deny list in PROSE is a finding, and so is a page over
+// its word budget. Code (fenced and inline), HTML comments and MDX import lines
+// are not prose, because `norsk-ctl instance launch-template` is a command the
+// reader types, not a word they have to understand.
+//
+// Usage:
+//   bun light-pages.ts [--root <dir>] [--allow w,w] [--deny w,w] [--max-words N] [file...]
+//
+// With no files it lints defaultLightPages(root). `--allow` is how a repo keeps
+// a word that is its own vocabulary. `instance` is deliberately not on the list:
+// it is the label on norsk-ctl's own screens, so every product's reader sees it.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, posix, relative } from "node:path";
+
+export interface LightFinding {
+  file: string;
+  line: number;
+  message: string;
+}
+
+export interface LightPagesOptions {
+  /** Words that must not appear in prose; defaults to DEFAULT_DENY. */
+  deny?: string[];
+  /** Words removed from the deny list for this repo. */
+  allow?: string[];
+  /** Prose word budget per page; unset means no budget. */
+  maxWords?: number;
+}
+
+/** The engineering vocabulary conventions/docs.md bans from reader-facing copy,
+ *  plus the words the October 2026 review found leaking onto quickstarts. */
+export const DEFAULT_DENY = [
+  "daemon",
+  "engine",
+  "fixture",
+  "fixtures",
+  "manifest",
+  "manifests",
+  "compose",
+  "harness",
+  "playwright",
+  "assertion",
+  "assertions",
+  "slug",
+  "slugs",
+  "ssr",
+  "zod",
+  "websocket",
+  "websockets",
+  "iframe",
+  "oauth2",
+];
+
+const FENCE = /^\s*(```|~~~)/;
+const INLINE_CODE = /`[^`\n]*`/g;
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
+const IMPORT_LINE = /^\s*import\s.*$/;
+
+/** The page with everything that is not prose blanked out, line structure kept
+ *  so findings can name a line. Frontmatter is prose: its description renders. */
+function proseLines(content: string): string[] {
+  const withoutComments = content
+    .replace(HTML_COMMENT, (m) => m.replace(/[^\n]/g, " "))
+    .replace(MDX_COMMENT, (m) => m.replace(/[^\n]/g, " "));
+  const out: string[] = [];
+  let inFence = false;
+  let inFrontmatter = false;
+  const lines = withoutComments.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (i === 0 && line.trim() === "---") {
+      inFrontmatter = true;
+      out.push("");
+      continue;
+    }
+    if (inFrontmatter) {
+      if (line.trim() === "---") inFrontmatter = false;
+      out.push("");
+      continue;
+    }
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      out.push("");
+      continue;
+    }
+    if (inFence || IMPORT_LINE.test(line)) {
+      out.push("");
+      continue;
+    }
+    out.push(line.replace(INLINE_CODE, " "));
+  }
+  return out;
+}
+
+function countWords(lines: string[]): number {
+  let n = 0;
+  for (const line of lines) {
+    const stripped = line.replace(/<[^>]+>/g, " ");
+    n += stripped.split(/\s+/).filter((w) => /[A-Za-z0-9]/.test(w)).length;
+  }
+  return n;
+}
+
+export function checkLightPage(file: string, content: string, opts: LightPagesOptions = {}): LightFinding[] {
+  const allow = new Set((opts.allow ?? []).map((w) => w.toLowerCase()));
+  const deny = (opts.deny ?? DEFAULT_DENY).map((w) => w.toLowerCase()).filter((w) => !allow.has(w));
+  const findings: LightFinding[] = [];
+  const lines = proseLines(content);
+  if (deny.length > 0) {
+    const pattern = new RegExp(`\\b(${deny.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`, "gi");
+    lines.forEach((line, i) => {
+      const seen = new Set<string>();
+      for (const m of line.matchAll(pattern)) {
+        const word = (m[1] ?? "").toLowerCase();
+        if (seen.has(word)) continue;
+        seen.add(word);
+        findings.push({
+          file,
+          line: i + 1,
+          message: `"${m[1]}" is engineering vocabulary; this page is written for a reader who does not know it. Say what it is in the product's own words, or move the sentence to How-to or Reference.`,
+        });
+      }
+    });
+  }
+  if (opts.maxWords !== undefined) {
+    const words = countWords(lines);
+    if (words > opts.maxWords) {
+      findings.push({
+        file,
+        line: 1,
+        message: `${words} words of prose against a budget of ${opts.maxWords}. Move options and alternatives to How-to; keep the happy path.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** A site's Start here pages and Guides, plus a repo's docs/quickstart.md:
+ *  the pages the lint applies to when the caller names none. */
+export function defaultLightPages(root: string): string[] {
+  const out: string[] = [];
+  const site = join(root, "website", "src", "content", "docs");
+  for (const name of ["index.md", "index.mdx", "quickstart.md", "quickstart.mdx"]) {
+    if (existsSync(join(site, name))) out.push(posix.join("website/src/content/docs", name));
+  }
+  const guides = join(site, "guides");
+  if (existsSync(guides)) {
+    const walk = (dir: string) => {
+      for (const name of readdirSync(dir).sort()) {
+        const p = join(dir, name);
+        if (statSync(p).isDirectory()) walk(p);
+        else if (/\.mdx?$/.test(name)) out.push(relative(root, p).split("\\").join("/"));
+      }
+    };
+    walk(guides);
+  }
+  if (existsSync(join(root, "docs", "quickstart.md"))) out.push("docs/quickstart.md");
+  return out;
+}
+
+export function checkLightPages(root: string, files: string[], opts: LightPagesOptions = {}): LightFinding[] {
+  const findings: LightFinding[] = [];
+  for (const file of files) {
+    const content = readFileSync(join(root, file), "utf8");
+    findings.push(...checkLightPage(file, content, opts));
+  }
+  return findings;
+}
+
+function parseArgs(argv: string[]): { root: string; files: string[]; opts: LightPagesOptions } {
+  let root = process.cwd();
+  const files: string[] = [];
+  const opts: LightPagesOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? "";
+    const next = () => argv[++i] ?? "";
+    if (a === "--root") root = next();
+    else if (a === "--allow") opts.allow = next().split(",").filter(Boolean);
+    else if (a === "--deny") opts.deny = next().split(",").filter(Boolean);
+    else if (a === "--max-words") opts.maxWords = Number(next());
+    else files.push(a);
+  }
+  return { root, files, opts };
+}
+
+if (import.meta.main) {
+  const { root, files, opts } = parseArgs(process.argv.slice(2));
+  const targets = files.length > 0 ? files : defaultLightPages(root);
+  const findings = checkLightPages(root, targets, opts);
+  if (findings.length === 0) {
+    console.log(`light-pages: OK (${targets.length} page${targets.length === 1 ? "" : "s"})`);
+  } else {
+    console.error(`light-pages: ${findings.length} finding${findings.length === 1 ? "" : "s"}`);
+    for (const f of findings) console.error(`  - ${f.file}:${f.line}: ${f.message}`);
+    process.exit(1);
+  }
+}

package/docs-theme/components/InstallProduct.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * The install section every product's Start here page carries: the one-line
+ * install, one sentence saying what it leaves you with, and one link into
+ * norsk-ctl's manual for everything about the machine. The line is a per-product
+ * FACT (norsk-ctl's deployment/products.json builds the script it fetches), so it
+ * is repeated on every site on purpose; the wording is shared so it cannot drift.
+ * Flags never appear here — the plan's rule for Start here pages — they live
+ * behind `moreHref`.
+ */
+interface Props {
+  /** The install slug: `curl .../install/<product>`. `ctl` for norsk-ctl itself. */
+  product: string;
+  /** What the reader has when the line finishes, one sentence, in the product's nouns. */
+  leaves: string;
+  /** Where the detail lives. Defaults to norsk-ctl's public manual. */
+  moreHref?: string;
+  /** Link text for `moreHref`. */
+  moreLabel?: string;
+}
+const {
+  product,
+  leaves,
+  moreHref = "https://ctl.norsk.video/how-to/install-options/",
+  moreLabel = "ports, TLS, cloud hosts, a box behind another proxy",
+} = Astro.props;
+const line = `curl -fsSL https://norsk.video/install/${product} | bash`;
+---
+
+<div class="install-product">
+  <pre class="install-product__line"><code>{line}</code></pre>
+  <p class="install-product__leaves">{leaves} It asks for what it needs and waits for a yes.</p>
+  <p class="install-product__more">Everything about the machine itself is in norsk-ctl's manual: <a href={moreHref}>{moreLabel}</a>.</p>
+</div>
+
+<style>
+  .install-product {
+    margin: 1.5rem 0;
+  }
+  .install-product__line {
+    margin: 0 0 0.75rem;
+  }
+  .install-product__leaves,
+  .install-product__more {
+    margin: 0 0 0.5rem;
+  }
+  .install-product__more {
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+  }
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.54",
+  "version": "0.2.55",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
@@ -14,6 +14,7 @@
     "./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/guide-stubs": "./docs/guide-stubs.ts",
     "./docs/path-existence": "./docs/path-existence.ts",
     "./docs/splice-generated": "./docs/splice-generated.ts",
     "./licence/check-entitlement": "./licence/check-entitlement.ts",