@norskvideo/ctl-dev-kit 0.1.15 → 0.1.17

package/conventions/CLAUDE.core.md

@@ -65,5 +65,16 @@
   (`norsk-ctl-product-playout`, `-commentary`) or beside the code they guard
   (`-probe`, `-turnkey-funke-pegasus`) is the repo's choice — the contract is
   the IDs and the guard, not the layout.
+- **Know who reads it — name the persona before writing docs or a
+  persona-facing surface.** Every Norsk ctl product writes for the same four
+  reader personas — Evaluator, Builder, Integrator, Operator (SRE) — defined in
+  `@norskvideo/ctl-dev-kit/conventions/personas.md`, with this product's own
+  audiences mapped onto them in its `docs/personas.md`. Before writing or
+  restructuring docs, a configure/dashboard surface, onboarding material, or any
+  copy a persona will read, name that reader and honour the ownership handoff
+  (Evaluator/Builder -> product repo, Operator -> ctl, Integrator -> both).
+  Runtime actors (the roles people play in the deployed product) are NOT
+  doc-reader personas: the operator who runs it is the Builder; guests who are
+  invited in receive onboarding kit, they don't read the manual.
 
 <!-- END ctl-shared-conventions v1 -->

package/conventions/check-drift.ts

@@ -211,6 +211,7 @@ export interface CanonicalBytes {
   core: string;
   flake: string;
   upgradeLatest: string;
+  syncDevKit: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -336,6 +337,22 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     );
   }
 
+  // sync-dev-kit.yml is OPTIONAL for the same reason as upgrade-latest.yml — a
+  // product may not carry it yet — but when present it is the shared,
+  // single-sourced workflow that keeps this repo's dev-kit pin fresh, and must
+  // not diverge. Only its `product:` dispatch key is per-repo.
+  const syncPath = join(repoRoot, ".github", "workflows", "sync-dev-kit.yml");
+  if (existsSync(syncPath)) {
+    push(
+      workflowProblem(
+        ".github/workflows/sync-dev-kit.yml",
+        "conventions/sync-dev-kit.yml",
+        readFileSync(syncPath, "utf8"),
+        canonical.syncDevKit,
+      ),
+    );
+  }
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -345,6 +362,7 @@ if (import.meta.main) {
     core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
+    syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "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/personas.md

@@ -0,0 +1,127 @@
+# Documentation personas (shared across all Norsk ctl product repos)
+
+The shared reader vocabulary. Every Norsk ctl product — probe, commentary,
+playout, the turnkeys — writes docs for the same four personas, so a reader who
+learns one product's docs knows how to navigate the next. Read this before
+writing or restructuring a product's `docs/`; then keep the product's own
+`docs/personas.md`, which maps *this* product's named audiences and runtime
+roles onto the four below.
+
+This is a **shipped reference**, not a drift-gated copy: you consume it from
+`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md`, you do not copy
+it into the repo. The per-product mapping legitimately differs product to
+product, so there is nothing byte-identical to gate — the shared thing is the
+vocabulary, not the mapping.
+
+## The four personas
+
+Two extremes (casual / deep-tech) miss the two middle personas that most docs
+actually serve. Each persona has a fixed sub-structure — Skills / Wants / Doc
+needs / Failure mode — so a product can fill it in the same shape.
+
+### 1. Evaluator
+
+Just heard about the product. A developer, a PM at a broadcaster, a technical
+founder — or a **sales engineer demoing it on their behalf**. Wants to know
+"does this do what I need?" in 15 minutes.
+
+- **Skills**: variable — assume no Docker / ffmpeg / transport-protocol knowledge.
+- **Wants**: a result on screen within a few minutes; clarity on what just
+  happened; confidence they won't hit a wall going further. A demo-driver also
+  wants it to read as credible and legible live on a shared screen.
+- **Doc needs**: one quick start, zero-to-running. Happy path only, no flags. A
+  gallery that shows the product's range at a glance.
+- **Failure mode**: opens a page with twelve sidebar entries (or a dense form),
+  bounces.
+
+### 2. Builder
+
+Building or standing up a real deployment *with* the product. A developer or a
+technical producer/operator. Wants it to work; does not want to become a DevOps
+expert, and does not want to hand-write config/graph YAML.
+
+- **Skills**: can run commands, knows what a container is. May be deeply fluent
+  in the product's *domain* (broadcast transports, say) while still not wanting
+  ctl/Docker internals — a product refines this in its own mapping.
+- **Wants**: task-oriented hand-holding; a UI that exposes everything; good
+  errors with fix hints; sensible defaults.
+- **Doc needs**: task guides ("how to do X") with screenshots. A troubleshooting
+  checklist. Not compose YAML, not env vars, not architecture diagrams.
+- **Failure mode**: hits an error, can't tell if it's their fault or a bug,
+  gives up.
+- **Usually the most underserved persona**, and usually the product's sweet
+  spot — the Integrator has generated reference, the Evaluator has zero-to-hero,
+  the Operator is largely ctl's; the Builder's task guides are the product's own
+  work and the thing most worth investing in.
+
+### 3. Integrator
+
+Automating against the product or wiring it into a larger system. Scripted
+launches, CI/CD, programmatic control.
+
+- **Skills**: comfortable with CLIs, API calls, shell; trusts tools, reads flags.
+- **Wants**: reference that matches reality; copy-pastable invocations; scripting
+  examples; clear error codes; idempotent operations for CI.
+- **Doc needs**: CLI reference (generated), API reference (from OpenAPI), a
+  config-file/schema reference, a short recipes page.
+- **Failure mode**: the reference has drifted from the tool; trust is lost; they
+  read the source instead.
+
+### 4. Operator (SRE)
+
+Running the product in production. Responsible for uptime, cost, security.
+
+- **Skills**: deep Docker, nginx/networking/TLS; reads source when docs are thin.
+- **Wants**: what the platform does to the host — ports bound, files touched,
+  where state lives, secrets, crash/restart, backup/restore, upgrade/DR.
+- **Doc needs**: an honest architecture doc, a production deployment guide, a
+  security reference.
+- **Failure mode**: docs are too happy-path, omit failure modes; can't tell if
+  the thing is production-ready.
+
+### On decision-makers
+
+CFO / commercial personas are a marketing concern, not a docs one. The useful
+middle is a **decision-maker evaluating for their team** — "should we build on
+this?" — served by one honest overview page (scale, maintenance, lock-in, CI),
+no marketing copy. Don't build a separate doc track for it.
+
+## Ownership: the persona handoff
+
+The persona a page serves decides which repo owns it, once products are split
+out of ctl:
+
+| Persona    | Owner repo    |
+| ---------- | ------------- |
+| Evaluator  | **product**   |
+| Builder    | **product**   |
+| Integrator | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
+| Operator   | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's |
+
+The test: **if the answer changes when you swap products, it's product docs; if
+it changes when you upgrade ctl, it's ctl docs.** Ownership is not presentation —
+a single rendered site can still interleave both (see norsk-ctl's
+`_planning/docs-after-the-split.md`).
+
+## Runtime actors are not doc-reader personas
+
+A deployed product has **runtime actors** — the roles people play in the running
+system (an operator at a console, a guest who joins, an analyst who reads a
+report). These are *not* a fifth, sixth, seventh persona, and indexing docs by
+them is the most common way a product's docs sprawl.
+
+Reconcile them like this:
+
+- The actor who **sets the deployment up and runs it** is the **Builder** (and,
+  live, the Operator in the ctl sense) — the same human, wearing hats. Their
+  material is the Builder task guides.
+- Actors who are **invited into** the running deployment (a guest, a
+  contributor) rarely read the manual at all — they receive a link, and maybe an
+  onboarding message. Material authored *for* them but *handed out by* the
+  Builder — join-page guides, onboarding email templates — is **distribution /
+  onboarding kit**, indexed separately from the Builder's own task guides, not
+  as manual chapters.
+
+Map each product's named audiences (from its `PRODUCT.md`) onto the four
+personas above; don't invent a parallel scheme. Keep the per-product mapping in
+the product's `docs/personas.md`.

package/conventions/sync-dev-kit.yml

@@ -0,0 +1,181 @@
+# Keep this product's shared conventions fresh against @norskvideo/ctl-dev-kit.
+# The dev-kit single-sources the files every ctl product would otherwise
+# copy-and-drift (the fenced CLAUDE.md core, flake.nix, the biome/tsconfig/dprint
+# bases, the shared workflows, the build bootstrap). check:drift fails CI when a
+# copy diverges from the *installed* dev-kit — so a product goes stale two ways:
+# its pin lags the newest published dev-kit, and once the pin bumps its copies
+# need re-syncing. This workflow closes the first gap and surfaces the second.
+#
+# It bumps the @norskvideo/ctl-dev-kit pin to the newest published version,
+# reinstalls, and runs this product's own gate (check:drift + lint + typecheck +
+# unit tests) against the new bytes:
+#
+#   - gate green -> a clean freshness bump; commit straight to main, like
+#     upgrade-latest.yml. The common case: a dev-kit release that doesn't touch
+#     this product's copies (or only verbatim ones already reconciled).
+#   - gate red   -> the new dev-kit needs a human: a drifted copy to re-sync, or
+#     a convention change that breaks this product. Push a branch and open a PR;
+#     check:drift's own output names each drifted file and the first diffing line.
+#     Re-sync on the branch until green, then merge.
+#
+# The re-sync is deliberately NOT automated. check:drift already emits the exact
+# fix, the masked / marker-block copies (the flake ctl pin, the CLAUDE core, the
+# dprint and gitignore blocks) need judgement, and a bot that blindly rewrote
+# them could commit a subtly-wrong splice. Detection plus a ready branch is the
+# leverage; the fix stays human.
+#
+# Single-sourced in @norskvideo/ctl-dev-kit (conventions/sync-dev-kit.yml) and
+# copied verbatim into each product repo; the check:drift gate fails CI if a copy
+# diverges. Only the `product:` value below is per-repo (set it to this repo's
+# dashboard key); everything else must match the dev-kit source. Never hand-edit
+# the copy -- edit the dev-kit source and re-sync.
+name: sync-dev-kit
+
+on:
+  schedule:
+    - cron: "37 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Resolve the newest published dev-kit and bump the pin
+        id: sync
+        run: |
+          set -euo pipefail
+          reg="https://registry.npmjs.org"
+          pkg="@norskvideo/ctl-dev-kit"
+          enc="@norskvideo%2Fctl-dev-kit"
+
+          # The runner has no npm; read the dist-tag off the registry with curl+jq
+          # (same as upgrade-latest.yml resolves the Norsk nightly).
+          new="$(curl -fsSL "$reg/$enc" | jq -r '."dist-tags".latest')"
+          [ -n "$new" ] && [ "$new" != "null" ] || { echo "could not resolve $pkg latest"; exit 1; }
+
+          # The current pin, whatever its range operator. A repo with no dev-kit
+          # dep has nothing to sync.
+          old="$(grep -oE "\"$pkg\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" package.json | head -1 | sed -E 's/.*"([^"]*)"$/\1/')"
+          if [ -z "$old" ]; then
+            echo "$pkg is not pinned in package.json -- nothing to sync."
+            echo "changed=0" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          old_bare="${old#^}"; old_bare="${old_bare#~}"
+          echo "dev-kit: $old -> ^$new"
+          if [ "$old_bare" = "$new" ]; then
+            echo "already on the newest dev-kit ($new)."
+            echo "changed=0" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # Surgical single-line rewrite so package.json keeps its formatting
+          # (a jq reserialize would reflow the whole file and trip the formatter).
+          sed -i -E "s|(\"$pkg\"[[:space:]]*:[[:space:]]*\")[^\"]*(\")|\1^$new\2|" package.json
+          echo "changed=1" >> "$GITHUB_OUTPUT"
+          echo "old=$old_bare" >> "$GITHUB_OUTPUT"
+          echo "new=$new" >> "$GITHUB_OUTPUT"
+
+      - name: Reinstall and run the product gate against the new dev-kit
+        id: gate
+        if: steps.sync.outputs.changed == '1'
+        continue-on-error: true
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install
+            bun run check:drift
+            bun run lint
+            bun run typecheck
+            bun run test:unit
+          '
+
+      - name: Land the freshness bump on main (gate green)
+        if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'success'
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "chore: sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }}
+
+          @norskvideo/ctl-dev-kit pin bumped to the newest published version;
+          check:drift + lint + typecheck + unit tests green against the new bytes.
+          Lockfile regenerated."
+          # A GITHUB_TOKEN push does not retrigger checks (Actions' recursion
+          # guard) -- fine, the gate above already ran them. Rebase-and-retry so a
+          # commit landing mid-run does not red the sync; a real conflict aborts.
+          for attempt in 1 2 3 4 5; do
+            if git push origin HEAD:main; then exit 0; fi
+            echo "push rejected (attempt $attempt) - rebasing onto latest origin/main"
+            git fetch origin main
+            git rebase origin/main || { git rebase --abort; echo "rebase hit a real conflict; aborting"; exit 1; }
+          done
+          echo "push still failing after 5 rebase attempts"; exit 1
+
+      - name: Open a reconciliation PR (gate red)
+        if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          branch="sync-dev-kit/${{ steps.sync.outputs.new }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add -A
+          git commit -m "chore: sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }} (needs reconciliation)"
+          git push -f origin "$branch"
+          title="Sync dev-kit ${{ steps.sync.outputs.old }} -> ${{ steps.sync.outputs.new }}"
+          body="$(printf '%s\n' \
+            "Automated dev-kit sync: the @norskvideo/ctl-dev-kit pin moved to the newest" \
+            "published version, but this product's gate is **red** against the new bytes," \
+            "so the sync needs a human." \
+            "" \
+            "Run the gate locally to see what to fix:" \
+            "" \
+            "    bun install" \
+            "    bun run check:drift   # names each drifted copy and the first diffing line" \
+            "    bun run lint && bun run typecheck && bun run test:unit" \
+            "" \
+            "Re-sync the named copies from node_modules/@norskvideo/ctl-dev-kit (never" \
+            "hand-edit against memory), or resolve the convention change this pin" \
+            "introduced, pushing to this branch until green -- then merge.")"
+          if existing="$(gh pr list --head "$branch" --state open --json number -q '.[0].number')" && [ -n "$existing" ]; then
+            gh pr edit "$existing" --title "$title" --body "$body"
+          else
+            gh pr create --base main --head "$branch" --title "$title" --body "$body"
+          fi
+
+      - name: Report "already fresh"
+        if: steps.sync.outputs.changed != '1'
+        run: echo "dev-kit pin already current -- nothing to sync."
+
+  # Report the sync result to the aggregated product CI dashboard
+  # (id3as/ci-workflows). always() so a failed sync shows a sad pony. A gate-red
+  # run that opened a PR is still a successful sync -- the red lives on the PR's
+  # own checks run, not here.
+  notify:
+    needs: sync
+    if: always()
+    runs-on: x64
+    steps:
+      - uses: actions/checkout@v5
+      - id: meta
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
+            echo "state=failure" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=success" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: ./.github/actions/ci-status-dispatch
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          product: __PRODUCT__
+          pipeline: dev-kit
+          status: ${{ steps.meta.outputs.state }}

package/create-product/canon.ts

@@ -17,6 +17,7 @@ export interface Canon {
   flake: string;
   flakeLock: string;
   upgradeLatest: string;
+  syncDevKit: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -32,6 +33,7 @@ export function loadCanon(): Canon {
     flake: readFileSync(join(buildDir, "flake.nix"), "utf8"),
     flakeLock: readFileSync(join(buildDir, "flake.lock"), "utf8"),
     upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
+    syncDevKit: readFileSync(join(conventionsDir, "sync-dev-kit.yml"), "utf8"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
     biome: readFileSync(join(conventionsDir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(conventionsDir, "tsconfig.base.json"), "utf8"),

package/create-product/create-product.ts

@@ -110,6 +110,7 @@ function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[]
     },
     { path: ".github/workflows/checks.yml", content: fillProduct(canon.checks) },
     { path: ".github/workflows/upgrade-latest.yml", content: fillProduct(canon.upgradeLatest) },
+    { path: ".github/workflows/sync-dev-kit.yml", content: fillProduct(canon.syncDevKit) },
     { path: ".github/actions/ci-status-dispatch/action.yml", content: loadAsset("ci-status-dispatch.yml") },
     { path: "manifest.seed.json", content: seedJson(ctx) },
     { path: "deployment/build-image.sh", content: buildImageWrapper(ctx), executable: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",