@norskvideo/ctl-dev-kit 0.2.58 → 0.2.60

package/conventions/check-drift.ts

@@ -5,7 +5,8 @@
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
 //     product with tests/demo.spec.ts is asked for it), publish-docs-site.yml
 //     (only a repo with a docs site may carry it, and never a turnkey)
-//   - masked per-repo line: checks.yml + upgrade-latest.yml (`product:` key)
+//   - masked per-repo line: checks.yml, upgrade-latest.yml, publish-docs.yml
+//     and the other dispatching workflows (`product:` key)
 //   - base + sanctioned extension block: dprint.json (repo-specific excludes)
 //   - must import the shared module: flake.nix (otherwise the product's own)
 //   - structural: root tsconfig.json (shape-dependent includes stay free),
@@ -789,18 +790,21 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   }
 
   // publish-docs.yml is OPTIONAL — a product carries it once it has an
-  // illustrated manual to publish nightly. Unlike the workflows above it has NO
-  // per-repo line: it is deliberately product-agnostic (per-repo bits live in
-  // scripts/doc-guide/regen-manual.sh + an optional prepull-extra.sh), so it is a
-  // verbatim byte-for-byte copy of the canonical.
+  // illustrated manual to publish nightly. Everything per-repo about the manual
+  // lives in scripts/doc-guide/regen-manual.sh (+ an optional prepull-extra.sh);
+  // the one per-repo line is the `product:` key its `docs` result is dispatched
+  // under, masked like checks.yml's. It was held verbatim when that dispatch was
+  // added, so the only passing copy was one that sent the placeholder.
   const publishDocsPath = join(repoRoot, ".github", "workflows", "publish-docs.yml");
   if (existsSync(publishDocsPath)) {
-    const actual = readFileSync(publishDocsPath, "utf8");
-    if (actual !== canonical.publishDocs) {
-      push(
-        `.github/workflows/publish-docs.yml has drifted from @norskvideo/ctl-dev-kit conventions/publish-docs.yml (${firstDiffLine(actual, canonical.publishDocs)}). ${RESYNC}`,
-      );
-    }
+    push(
+      workflowProblem(
+        ".github/workflows/publish-docs.yml",
+        "conventions/publish-docs.yml",
+        readFileSync(publishDocsPath, "utf8"),
+        canonical.publishDocs,
+      ),
+    );
   }
 
   // build-docs.yml is the embedded twin of publish-docs.yml: optional, verbatim.

package/conventions/publish-docs.yml

@@ -13,12 +13,12 @@
 #     whenever it builds its docs.
 #
 # This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
-# (conventions/publish-docs.yml) and copied verbatim, same as checks.yml. It is
-# deliberately product-agnostic: everything per-repo lives in repo-local scripts
-# it calls —
+# (conventions/publish-docs.yml) and copied verbatim, same as checks.yml: only
+# the `product:` value below is per-repo (set it to this repo's dashboard key).
+# Everything else per-repo lives in repo-local scripts it calls —
 #   - scripts/doc-guide/regen-manual.sh   : the guide tiers + slug list + assemble
 #   - scripts/doc-guide/prepull-extra.sh  : OPTIONAL, any images beyond media+studio
-# so the drift gate can keep every product's copy byte-identical.
+# so the drift gate can keep every product's copy otherwise byte-identical.
 #
 # Nightly-only by design: a guide's engine tier stands up real instances (slow,
 # and subject to teardown flakes), so it does not ride every push. The

package/conventions/sync-drift.ts

@@ -7,7 +7,8 @@
 // It only touches copies whose convergent form is mechanical — there is no
 // judgement anywhere:
 //   - verbatim (biome.json, tsconfig.base.json)      -> overwrite with canonical
-//   - masked workflows (checks / upgrade / sync)     -> canonical, repo's product: key kept
+//   - masked workflows (checks / upgrade / sync /    -> canonical, repo's product: key kept
+//     publish-docs)
 //   - nix/ctl-shell.nix                              -> overwrite with canonical (created if absent)
 //   - flake.nix (legacy verbatim copy only)          -> the starter, repo's floating ctl pin kept
 //   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
@@ -86,6 +87,28 @@ function syncWorkflow(repoRoot: string, rel: string, canonical: string, r: SyncR
   writeIfChanged(path, canonical.replace(PRODUCT_LINE, `$1${key}`), rel, r.written);
 }
 
+// publish-docs.yml: optional, and masked like checks.yml (only re-synced where
+// the repo already carries it). Every copy predating the mask was written
+// verbatim with the sentinel, so a copy with no key of its own takes the one
+// checks.yml (required, and always filled) dispatches under — otherwise no
+// nightly could ever converge those copies.
+function syncPublishDocs(repoRoot: string, canonical: string, r: SyncReport): void {
+  const rel = ".github/workflows/publish-docs.yml";
+  const path = join(repoRoot, rel);
+  if (!existsSync(path)) return;
+  const own = readFileSync(path, "utf8").match(/^\s*product:\s*(\S+)/m)?.[1];
+  const checksPath = join(repoRoot, ".github/workflows/checks.yml");
+  const fromChecks = existsSync(checksPath)
+    ? readFileSync(checksPath, "utf8").match(/^\s*product:\s*(\S+)/m)?.[1]
+    : undefined;
+  const key = own && own !== PRODUCT_SENTINEL ? own : fromChecks;
+  if (!key || key === PRODUCT_SENTINEL) {
+    r.skipped.push(`${rel} (no product: key to preserve)`);
+    return;
+  }
+  writeIfChanged(path, canonical.replace(PRODUCT_LINE, `$1${key}`), rel, r.written);
+}
+
 // build-image.yml: canonical byte-for-byte except two per-repo lines — the
 // notify job's `product:` dispatch key and the PUBLISH_IMAGE env (the Docker Hub
 // repo, or empty for a build-only product). Re-emit the canonical with both of
@@ -376,12 +399,7 @@ export function syncDrift(
   syncSmoke(repoRoot, canonical.smoke, r);
   syncIntegration(repoRoot, canonical.integration, r);
 
-  // publish-docs.yml is optional and verbatim (no per-repo line) — only re-sync a
-  // repo that already carries it, unlike biome/tsconfig which every repo must have.
-  const publishDocsRel = ".github/workflows/publish-docs.yml";
-  if (existsSync(join(repoRoot, publishDocsRel))) {
-    writeIfChanged(join(repoRoot, publishDocsRel), canonical.publishDocs, publishDocsRel, r.written);
-  }
+  syncPublishDocs(repoRoot, canonical.publishDocs, r);
   // build-docs.yml, the embedded variant, the same way: carrying it is the
   // repo's declaration (ADR-0012); sync only keeps the copy verbatim.
   const buildDocsRel = ".github/workflows/build-docs.yml";

package/doc-guide/doc-guide.d.ts

@@ -28,11 +28,13 @@ export declare function docsRoot(): string;
  *  at about 2.5 words/s: 35 words is 14 s on one still, 50 is 20 s, and the
  *  renderer's own lint warns at 35. This is the hard stop. */
 export declare const DEFAULT_CAPTION_WORDS = 50;
+/** The part of a step's text that is narrated: everything but its fenced blocks. */
+export declare function spokenText(text: string): string;
 /** Why a step's text cannot be narrated as written, or null when it can. Pure,
  *  so the wording is pinned without a browser. Checks the budget first: an
  *  over-long caption gets rewritten anyway, and the rewrite is where the
- *  phrasing gets fixed. */
-export declare function captionFault(text: string, budget: number): string | null;
+ *  phrasing gets fixed. Only the spoken part is held to either. */
+export declare function captionFault(caption: string, budget: number): string | null;
 /** Device scale factor for a capture: 2 in a DOCS_GENERATE run, 1 otherwise.
  *  The video spike found the manual's component crops 383 to 778 px wide; in
  *  a 1080p frame they are soft, and no renderer recovers detail that was never

package/doc-guide/doc-guide.js

@@ -17,11 +17,19 @@ export const DEFAULT_CAPTION_WORDS = 50;
 const SPOKEN_WORD = /[\p{L}\p{N}]/u;
 const RAW_URL = /https?:\/\/\S+/;
 const SLASH_BETWEEN_WORDS = /\S+\/\S+/;
+/** A fenced block (``` or ~~~, closed or running to the end as markdown has
+ *  it) is a transcript or a file to copy: the page shows it, nobody speaks it. */
+const FENCED_BLOCK = /^(`{3,}|~{3,})[^\n]*$[\s\S]*?(?:^\1[ \t]*$|(?![\s\S]))/gm;
+/** The part of a step's text that is narrated: everything but its fenced blocks. */
+export function spokenText(text) {
+    return text.replace(FENCED_BLOCK, "");
+}
 /** Why a step's text cannot be narrated as written, or null when it can. Pure,
  *  so the wording is pinned without a browser. Checks the budget first: an
  *  over-long caption gets rewritten anyway, and the rewrite is where the
- *  phrasing gets fixed. */
-export function captionFault(text, budget) {
+ *  phrasing gets fixed. Only the spoken part is held to either. */
+export function captionFault(caption, budget) {
+    const text = spokenText(caption);
     const count = text.split(/\s+/).filter((token) => SPOKEN_WORD.test(token)).length;
     if (count > budget)
         return `${count} words; the spoken budget is ${budget}`;

package/package.json

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