@norskvideo/ctl-dev-kit 0.1.67 → 0.1.69

package/conventions/check-drift.ts

@@ -254,6 +254,11 @@ export interface CanonicalBytes {
   smoke: string;
   /** conventions/demo.sh — the scripts/demo shim a product with tests/demo.spec.ts carries. */
   demoShim: string;
+  /** doc-guide/with-display.sh — the X-display wrapper BOTH docs workflows invoke
+   *  as `scripts/with-display.sh`. Gated because the workflow is: an ungated
+   *  hand copy is how build-docs.yml came to fail in both turnkeys, which never
+   *  made one. */
+  withDisplay: string;
 }
 
 // 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
@@ -568,6 +573,32 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   }
   for (const p of docsExposureProblems(existsSync(publishDocsPath), existsSync(buildDocsPath), opts.repoName)) push(p);
 
+  // Both docs workflows run `bash scripts/with-display.sh scripts/doc-guide/...`.
+  // The workflow is gated byte-for-byte and the script it invokes was not gated
+  // at all, so a repo could satisfy the gate and still have no way to run the
+  // step: build-docs.yml failed on its first scheduled run in BOTH turnkeys with
+  // "bash: scripts/with-display.sh: No such file or directory", after the prose
+  // bundle had already built. It stays a repo-local executable on purpose (the
+  // package.json guide scripts invoke it by that path); it is the ABSENCE from
+  // the gate that was the bug.
+  const carriesDocs = existsSync(publishDocsPath) || existsSync(buildDocsPath);
+  if (carriesDocs) {
+    const which = existsSync(buildDocsPath) ? "build-docs.yml" : "publish-docs.yml";
+    const withDisplayPath = join(repoRoot, "scripts", "with-display.sh");
+    if (!existsSync(withDisplayPath)) {
+      push(
+        `.github/workflows/${which} runs \`bash scripts/with-display.sh\`, but this repo has no scripts/with-display.sh — the step cannot run. ${RESYNC}`,
+      );
+    } else {
+      const actual = readFileSync(withDisplayPath, "utf8");
+      if (actual !== canonical.withDisplay) {
+        push(
+          `scripts/with-display.sh has drifted from @norskvideo/ctl-dev-kit doc-guide/with-display.sh (${firstDiffLine(actual, canonical.withDisplay)}). ${RESYNC}`,
+        );
+      }
+    }
+  }
+
   for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
 
   return { ok: problems.length === 0, problems };
@@ -583,6 +614,7 @@ if (import.meta.main) {
     syncCtlPackages: readFileSync(join(import.meta.dir, "sync-ctl-packages.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
+    withDisplay: readFileSync(join(import.meta.dir, "..", "doc-guide", "with-display.sh"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),

package/conventions/sync-drift.ts

@@ -214,6 +214,22 @@ function syncDemoShim(repoRoot: string, canonical: string, r: SyncReport): void
   chmodSync(path, 0o755);
 }
 
+// Both docs workflows run `bash scripts/with-display.sh ...`. It stays a
+// repo-local executable (the package.json guide scripts invoke it by that path),
+// so a repo that carries a docs workflow gets the canonical copy written here
+// rather than hand-copied — which is what neither turnkey ever did.
+function syncWithDisplay(repoRoot: string, canonical: string, r: SyncReport): void {
+  const carriesDocs =
+    existsSync(join(repoRoot, ".github/workflows/publish-docs.yml")) ||
+    existsSync(join(repoRoot, ".github/workflows/build-docs.yml"));
+  if (!carriesDocs) return;
+  const rel = "scripts/with-display.sh";
+  const path = join(repoRoot, rel);
+  mkdirSync(dirname(path), { recursive: true });
+  writeIfChanged(path, canonical, rel, r.written);
+  chmodSync(path, 0o755);
+}
+
 export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncReport {
   const r: SyncReport = { written: [], skipped: [] };
 
@@ -253,6 +269,7 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
   syncDemoShim(repoRoot, canonical.demoShim, r);
+  syncWithDisplay(repoRoot, canonical.withDisplay, r);
 
   return r;
 }
@@ -268,6 +285,7 @@ if (import.meta.main) {
     syncCtlPackages: readFileSync(join(dir, "sync-ctl-packages.yml"), "utf8"),
     publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(dir, "build-docs.yml"), "utf8"),
+    withDisplay: readFileSync(join(dir, "..", "doc-guide", "with-display.sh"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(dir, "tsconfig.base.json"), "utf8"),

package/create-product/backend-turnkey.ts

@@ -1616,6 +1616,7 @@ export const backendTurnkey: ShapeModule = {
       { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },
       { path: ".github/workflows/build-docs.yml", content: ctx.canon.buildDocs },
       { path: "scripts/doc-guide/regen-manual.sh", content: REGEN_MANUAL_SH, executable: true },
+      { path: "scripts/with-display.sh", content: ctx.canon.withDisplay, executable: true },
       { path: "scripts/docs-handover.sh", content: DOCS_HANDOVER_SH, executable: true },
       { path: "tests/demo.spec.ts", content: demoSpecTs(ctx) },
       { path: "tests/unit/demo-spec.test.ts", content: DEMO_SPEC_TEST_TS },

package/create-product/canon.ts

@@ -31,6 +31,9 @@ export interface Canon {
   invariantsTemplate: string;
   /** conventions/demo.sh, emitted as scripts/demo. */
   demoShim: string;
+  /** doc-guide/with-display.sh, emitted as scripts/with-display.sh — the docs
+   *  workflow invokes it by that repo-local path. */
+  withDisplay: string;
 }
 
 export function loadCanon(): Canon {
@@ -43,6 +46,7 @@ export function loadCanon(): Canon {
     syncCtlPackages: readFileSync(join(conventionsDir, "sync-ctl-packages.yml"), "utf8"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
     buildDocs: readFileSync(join(conventionsDir, "build-docs.yml"), "utf8"),
+    withDisplay: readFileSync(join(conventionsDir, "..", "doc-guide", "with-display.sh"), "utf8"),
     biome: readFileSync(join(conventionsDir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(conventionsDir, "tsconfig.base.json"), "utf8"),
     dprint: readFileSync(join(conventionsDir, "dprint.base.jsonc"), "utf8"),

package/licence/check-template.ts

@@ -0,0 +1,117 @@
+// Lint a repo's licenceTemplate.json against what the repo actually is.
+//
+// The template is this repo's half of a licence: the `products[]` entries a
+// grant needs in order to entitle it. Minting composes {a grant's header} +
+// {the union of one or more repos' entries}, so a template that names the wrong
+// product — or an imageRef the build never produces — mints a licence that
+// entitles nothing, and the first sign is a 60-second readiness timeout.
+//
+// That is not hypothetical. licensing/partner-all-products-template.json is
+// hand-maintained, names four products, and has silently omitted both turnkeys
+// for as long as they have existed. This lint is what makes the derived
+// version impossible to get wrong the same way.
+//
+// It asserts recorded INTENT matches reality, not security: a user can retag
+// any image, so imageRef buys no defence. What it buys is a statement of what
+// was meant, which is only worth having if something keeps it true.
+import { readFileSync } from "node:fs";
+
+export interface RepoFacts {
+  /** The repo's own PRODUCT_NAME. */
+  product: string;
+  /** The image name CI builds under — see builtImageName. */
+  image: string;
+}
+
+/** The image name CI builds under, by CI's own rule: PUBLISH_IMAGE when set,
+ *  else the build script's IMAGE_TAG default, tag stripped. The licence matches
+ *  on the repo part alone (`imageRefMatches`: `parsed.repo !== entry.imageRef`),
+ *  so the tag never belongs in a template. */
+export function builtImageName(opts: { publishImage: string; buildDefault: string }): string | null {
+  const ref = opts.publishImage.trim() || opts.buildDefault.trim();
+  if (!ref) return null;
+  // Strip a tag, but not a registry port: a colon is a tag only after the last slash.
+  const lastSlash = ref.lastIndexOf("/");
+  const colon = ref.indexOf(":", lastSlash + 1);
+  return colon === -1 ? ref : ref.slice(0, colon);
+}
+
+const REQUIRED_ENTRY_FIELDS = ["product", "imageRef", "versionConstraint", "mode"] as const;
+
+/** Fields that describe WHO a licence was cut for. A repo does not know them,
+ *  and a merged staff licence that inherited one repo's expiry would be a
+ *  quiet, dated surprise. */
+const GRANT_ONLY_FIELDS = ["issuedTo", "email", "expiry", "timeout", "nonProduction"] as const;
+
+export function templateProblems(templateJson: string, repo: RepoFacts): string[] {
+  let parsed: { products?: unknown } & Record<string, unknown>;
+  try {
+    parsed = JSON.parse(templateJson);
+  } catch (e) {
+    return [`licenseTemplate.json is not valid JSON: ${String(e)}`];
+  }
+  if (typeof parsed !== "object" || parsed === null) return ["licenseTemplate.json is not an object"];
+
+  const problems: string[] = [];
+  for (const f of GRANT_ONLY_FIELDS) {
+    if (f in parsed) {
+      problems.push(`licenseTemplate.json carries "${f}", which belongs to the grant, not the repo — remove it`);
+    }
+  }
+  if (!Array.isArray(parsed.products)) {
+    problems.push('licenseTemplate.json has no "products" array');
+    return problems;
+  }
+
+  const entries = parsed.products as Record<string, unknown>[];
+  for (const [i, entry] of entries.entries()) {
+    for (const f of REQUIRED_ENTRY_FIELDS) {
+      if (typeof entry?.[f] !== "string") problems.push(`products[${i}] is missing "${f}"`);
+    }
+    const ref = entry?.imageRef;
+    if (typeof ref === "string") {
+      const lastSlash = ref.lastIndexOf("/");
+      if (ref.indexOf(":", lastSlash + 1) !== -1) {
+        problems.push(`products[${i}].imageRef "${ref}" carries a tag; a licence matches the repo part only`);
+      }
+    }
+  }
+
+  const named = entries.map((e) => e?.product).filter((p): p is string => typeof p === "string");
+  if (!named.includes(repo.product)) {
+    problems.push(
+      `licenseTemplate.json does not name this repo's product ${repo.product} (names: ${named.join(", ") || "nothing"})`,
+    );
+    return problems;
+  }
+
+  const mine = entries.find((e) => e?.product === repo.product);
+  if (typeof mine?.imageRef === "string" && mine.imageRef !== repo.image) {
+    problems.push(`products[].imageRef for ${repo.product} is "${mine.imageRef}" but this repo builds "${repo.image}"`);
+  }
+  return problems;
+}
+
+if (import.meta.main) {
+  const [file, product, image] = process.argv.slice(2);
+  if (!file || !product || !image) {
+    console.error("usage: check-template.ts <licenseTemplate.json> <product-name> <built-image-name>");
+    process.exit(2);
+  }
+  let contents: string;
+  try {
+    contents = readFileSync(file, "utf8");
+  } catch {
+    // Absence is not yet an error: the turnkeys' templates wait on their
+    // customer-facing image names being settled. Flipping this to a failure is
+    // a one-line change once every repo carries one.
+    console.log(`licence-template: no ${file} — not yet required in this repo`);
+    process.exit(0);
+  }
+  const problems = templateProblems(contents, { product, image });
+  if (problems.length) {
+    for (const p of problems) console.error(`licence-template: ${p}`);
+    process.exit(1);
+  }
+  console.log(`licence-template: ${file} names ${product} at ${image}`);
+}

package/package.json

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