@norskvideo/ctl-dev-kit 0.1.18 → 0.1.19

package/conventions/check-drift.ts

@@ -25,8 +25,14 @@ export interface DriftReport {
   problems: string[];
 }
 
-const BEGIN = "<!-- BEGIN ctl-shared-conventions v1 -->";
-const END = "<!-- END ctl-shared-conventions v1 -->";
+export const BEGIN = "<!-- BEGIN ctl-shared-conventions v1 -->";
+export const END = "<!-- END ctl-shared-conventions v1 -->";
+
+// The .gitignore shared block is delimited by these markers (see gitignore.core),
+// so the sync writer can locate-and-replace it deterministically. The gate itself
+// checks the whole marker-delimited block as a verbatim substring.
+export const GITIGNORE_BEGIN = "# BEGIN ctl-shared-gitignore v1";
+export const GITIGNORE_END = "# END ctl-shared-gitignore v1";
 
 const RESYNC = "Edit the dev-kit source and re-sync — never hand-edit the copy.";
 
@@ -45,8 +51,8 @@ function firstDiffLine(actual: string, expected: string): string {
 
 // The one legitimately per-repo line in the shared workflows: the dashboard key
 // the CI result is dispatched under. Everything else is verbatim-shared.
-const PRODUCT_LINE = /^(\s*product:\s*).*$/gm;
-const PRODUCT_SENTINEL = "__PRODUCT__";
+export const PRODUCT_LINE = /^(\s*product:\s*).*$/gm;
+export const PRODUCT_SENTINEL = "__PRODUCT__";
 
 function workflowProblem(relPath: string, canonicalRef: string, actual: string, canonical: string): string | undefined {
   // Compare structure with the product value masked so any real key passes, then
@@ -66,8 +72,8 @@ function workflowProblem(relPath: string, canonicalRef: string, actual: string,
 // this pin only feeds the dev flake; it floats per repo and over time and is NOT
 // a shared convention. Mask it so the gate compares flake STRUCTURE, not the pin
 // — same idea as masking upgrade-latest's product: line.
-const CTL_VERSION_LINE = /ctlVersion = "[^"]*";/;
-const CTL_HASH_LINE = /hash = "sha256-[^"]*";/g;
+export const CTL_VERSION_LINE = /ctlVersion = "[^"]*";/;
+export const CTL_HASH_LINE = /hash = "sha256-[^"]*";/g;
 
 function flakeProblem(actual: string, canonical: string): string | undefined {
   const mask = (s: string) =>
@@ -82,10 +88,10 @@ function flakeProblem(actual: string, canonical: string): string | undefined {
 // inside a sanctioned marker block at the head of `excludes`. Everything outside
 // the block is byte-compared; inside, only well-formed `"entry",` lines are
 // allowed so the block can't smuggle arbitrary config past the byte check.
-const DPRINT_BEGIN = "// BEGIN repo-specific excludes";
-const DPRINT_END = "// END repo-specific excludes";
+export const DPRINT_BEGIN = "// BEGIN repo-specific excludes";
+export const DPRINT_END = "// END repo-specific excludes";
 
-function splitAtMarkers(s: string): { prefix: string; body: string[]; suffix: string } | undefined {
+export function splitAtMarkers(s: string): { prefix: string; body: string[]; suffix: string } | undefined {
   const lines = s.split("\n");
   const begin = lines.findIndex((l) => l.trim() === DPRINT_BEGIN);
   const end = lines.findIndex((l) => l.trim() === DPRINT_END);

package/conventions/sync-dev-kit.yml

@@ -7,22 +7,21 @@
 # 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:
+# reinstalls, re-syncs this product's forced copies from the new canonical
+# (sync-drift), then runs the gate (check:drift + lint + typecheck + unit tests):
 #
-#   - 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.
+#   - gate green -> the bump plus any mechanical re-sync is correct; commit it all
+#     straight to main, hands-free. This is the common case.
+#   - gate red   -> the new dev-kit genuinely does not fit this product: a
+#     convention that fails lint/typecheck/tests, or a copy sync-drift could not
+#     mechanically converge. Push a branch and open a PR for a human -- real
+#     engineering to adopt the convention, not a copy-paste.
 #
-# 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.
+# sync-drift re-derives each copy from the canonical (never a second opinion that
+# can disagree), preserving the per-repo bits the gate masks -- the product: keys,
+# the flake ctl pin, the dprint/gitignore/CLAUDE repo content. The gate runs AFTER
+# it, so a bad rewrite fails check:drift and a breaking convention fails the build,
+# rather than landing silently. Structural per-repo files it never touches.
 #
 # 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
@@ -81,7 +80,7 @@ jobs:
           echo "old=$old_bare" >> "$GITHUB_OUTPUT"
           echo "new=$new" >> "$GITHUB_OUTPUT"
 
-      - name: Reinstall and run the product gate against the new dev-kit
+      - name: Reinstall, re-sync the copies from canonical, run the product gate
         id: gate
         if: steps.sync.outputs.changed == '1'
         continue-on-error: true
@@ -89,6 +88,7 @@ jobs:
           nix develop .#build --command bash -c '
             set -euo pipefail
             bun install
+            bun run node_modules/@norskvideo/ctl-dev-kit/conventions/sync-drift.ts
             bun run check:drift
             bun run lint
             bun run typecheck
@@ -104,9 +104,10 @@ jobs:
           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."
+          @norskvideo/ctl-dev-kit pin bumped to the newest published version and the
+          forced copies re-synced from the new canonical (sync-drift); 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.
@@ -134,18 +135,17 @@ jobs:
           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." \
+            "published version and sync-drift re-synced the forced copies from the new" \
+            "canonical -- but the gate is **red**, so this bump needs a human." \
             "" \
-            "Run the gate locally to see what to fix:" \
+            "The mechanical re-sync is already on this branch. A red gate here means the" \
+            "new dev-kit genuinely does not fit the product yet -- run the gate to see which:" \
             "" \
             "    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" \
+            "    bun run check:drift   # a copy sync-drift could not mechanically converge" \
+            "    bun run lint && bun run typecheck && bun run test:unit   # a convention that breaks real code" \
             "" \
-            "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.")"
+            "Resolve whichever is failing, 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

package/conventions/sync-drift.ts

@@ -0,0 +1,190 @@
+// The writer half of the drift gate. check-drift.ts proves a product's forced
+// copies match this dev-kit's canonical; sync-drift.ts *makes* them match, by
+// re-deriving each copy from the same canonical bytes. It is the mechanical
+// inverse of the checker and shares its constants (imported below) so the two
+// cannot disagree about what "in sync" means.
+//
+// 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
+//   - flake.nix                                      -> canonical, repo's floating ctl pin kept
+//   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
+// Structural per-repo files (root tsconfig.json, deployment/build-image.sh,
+// manifest.seed.json) have NO canonical bytes to apply — the gate checks their
+// shape, not their content — so they are left untouched.
+//
+// The safety net is that the gate still runs AFTER sync: a copy this writer
+// cannot mechanically converge (e.g. a workflow with no product key to preserve)
+// is left for check-drift to flag, and a convention that genuinely breaks the
+// product surfaces as a red lint/typecheck/test — not as a silent bad copy.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BEGIN,
+  type CanonicalBytes,
+  CTL_HASH_LINE,
+  CTL_VERSION_LINE,
+  END,
+  GITIGNORE_BEGIN,
+  GITIGNORE_END,
+  PRODUCT_LINE,
+  PRODUCT_SENTINEL,
+  splitAtMarkers,
+} from "./check-drift.ts";
+
+export interface SyncReport {
+  written: string[];
+  skipped: string[];
+}
+
+function writeIfChanged(path: string, content: string, rel: string, written: string[]): void {
+  const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
+  if (current !== content) {
+    writeFileSync(path, content);
+    written.push(rel);
+  }
+}
+
+// checks.yml / upgrade-latest.yml / sync-dev-kit.yml: canonical byte-for-byte
+// except the one `product:` dispatch key, which the gate masks. Re-emit the
+// canonical with the repo's own key filled back in. A workflow with no key to
+// preserve (absent, or still the sentinel) is left for the gate to flag.
+function syncWorkflow(repoRoot: string, rel: string, canonical: string, r: SyncReport): void {
+  const path = join(repoRoot, rel);
+  if (!existsSync(path)) {
+    r.skipped.push(`${rel} (absent)`);
+    return;
+  }
+  const key = readFileSync(path, "utf8").match(/^\s*product:\s*(\S+)/m)?.[1];
+  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);
+}
+
+// flake.nix is verbatim except the dev-only ctl pin (ctlVersion + the four
+// per-platform hashes), which floats per repo. Re-emit canonical STRUCTURE with
+// the repo's pin restored in order — so a structural edit (e.g. a stray comment)
+// is replaced while the pin is kept. Structure is identical across repos, so the
+// Nth hash line in canonical maps to the Nth in the repo.
+function syncFlake(repoRoot: string, canonical: string, r: SyncReport): void {
+  const path = join(repoRoot, "flake.nix");
+  if (!existsSync(path)) {
+    r.skipped.push("flake.nix (absent)");
+    return;
+  }
+  const existing = readFileSync(path, "utf8");
+  const version = existing.match(CTL_VERSION_LINE)?.[0];
+  const hashes = existing.match(CTL_HASH_LINE) ?? [];
+  let out = version ? canonical.replace(CTL_VERSION_LINE, version) : canonical;
+  let i = 0;
+  out = out.replace(CTL_HASH_LINE, (m) => hashes[i++] ?? m);
+  writeIfChanged(path, out, "flake.nix", r.written);
+}
+
+// Replace the region between two markers with the canonical block, preserving
+// everything outside it. `canonicalBlock` starts at the BEGIN marker and ends at
+// the END marker.
+function replaceMarkerBlock(existing: string, begin: string, end: string, canonicalBlock: string): string | undefined {
+  const b = existing.indexOf(begin);
+  const e = existing.indexOf(end);
+  if (b === -1 || e === -1 || e < b) return undefined;
+  const after = existing.slice(e + end.length);
+  return existing.slice(0, b) + canonicalBlock.trimEnd() + (after.startsWith("\n") ? after : `\n${after}`);
+}
+
+// CLAUDE.md: the fenced conventions core lives between the markers; the repo's
+// own intro/outro prose is outside and kept.
+function syncClaude(repoRoot: string, core: string, r: SyncReport): void {
+  const path = join(repoRoot, "CLAUDE.md");
+  if (!existsSync(path)) {
+    r.skipped.push("CLAUDE.md (absent)");
+    return;
+  }
+  const out = replaceMarkerBlock(readFileSync(path, "utf8"), BEGIN, END, core);
+  if (out === undefined) {
+    r.skipped.push("CLAUDE.md (no marker block)");
+    return;
+  }
+  writeIfChanged(path, out, "CLAUDE.md", r.written);
+}
+
+// .gitignore: the shared block is marker-delimited; repo-specific ignores live
+// outside it. Replace the block, or prepend it if the repo has none yet (the
+// one-time migration case).
+function syncGitignore(repoRoot: string, canonicalCore: string, r: SyncReport): void {
+  const path = join(repoRoot, ".gitignore");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const replaced = replaceMarkerBlock(existing, GITIGNORE_BEGIN, GITIGNORE_END, canonicalCore);
+  const out = replaced ?? `${canonicalCore.trimEnd()}\n${existing}`;
+  writeIfChanged(path, out, ".gitignore", r.written);
+}
+
+// dprint.json: canonical outside the repo-specific-excludes markers, the repo's
+// own exclude entries kept between them.
+function syncDprint(repoRoot: string, canonical: string, r: SyncReport): void {
+  const path = join(repoRoot, "dprint.json");
+  if (!existsSync(path)) {
+    r.skipped.push("dprint.json (absent)");
+    return;
+  }
+  const c = splitAtMarkers(canonical);
+  if (!c) throw new Error("canonical dprint.base.jsonc is missing its own marker block");
+  const a = splitAtMarkers(readFileSync(path, "utf8"));
+  if (!a) {
+    r.skipped.push("dprint.json (no marker block)");
+    return;
+  }
+  // splitAtMarkers keeps the file's trailing newline as an empty final line in
+  // suffix, so the join alone reproduces it — appending another would drift.
+  const out = [c.prefix, ...a.body, c.suffix].join("\n");
+  writeIfChanged(path, out, "dprint.json", r.written);
+}
+
+export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncReport {
+  const r: SyncReport = { written: [], skipped: [] };
+
+  writeIfChanged(join(repoRoot, "biome.json"), canonical.biome, "biome.json", r.written);
+  writeIfChanged(join(repoRoot, "tsconfig.base.json"), canonical.tsconfigBase, "tsconfig.base.json", r.written);
+
+  syncWorkflow(repoRoot, ".github/workflows/checks.yml", canonical.checks, r);
+  syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
+  syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
+
+  syncFlake(repoRoot, canonical.flake, r);
+  syncClaude(repoRoot, canonical.core, r);
+  syncGitignore(repoRoot, canonical.gitignoreCore, r);
+  syncDprint(repoRoot, canonical.dprint, r);
+
+  return r;
+}
+
+if (import.meta.main) {
+  const repoRoot = process.argv[2] ?? process.cwd();
+  const dir = import.meta.dir;
+  const canonical: CanonicalBytes = {
+    core: readFileSync(join(dir, "CLAUDE.core.md"), "utf8"),
+    flake: readFileSync(join(dir, "..", "build", "flake.nix"), "utf8"),
+    upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
+    syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
+    checks: readFileSync(join(dir, "checks.yml"), "utf8"),
+    biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
+    tsconfigBase: readFileSync(join(dir, "tsconfig.base.json"), "utf8"),
+    dprint: readFileSync(join(dir, "dprint.base.jsonc"), "utf8"),
+    buildImageBootstrap: readFileSync(join(dir, "..", "build", "build-image.bootstrap.sh"), "utf8"),
+    gitignoreCore: readFileSync(join(dir, "gitignore.core"), "utf8"),
+  };
+  const report = syncDrift(repoRoot, canonical);
+  if (report.written.length === 0) {
+    console.log("sync-drift: all shared-convention copies already match @norskvideo/ctl-dev-kit.");
+  } else {
+    console.log(`sync-drift: rewrote ${report.written.length} copy(ies) from @norskvideo/ctl-dev-kit:`);
+    for (const w of report.written) console.log(`  - ${w}`);
+  }
+  if (report.skipped.length > 0) {
+    console.log("left for check-drift / a human:");
+    for (const s of report.skipped) console.log(`  - ${s}`);
+  }
+}

package/create-product/backend-turnkey.ts

@@ -111,6 +111,7 @@ function rootPackageJson(ctx: ShapeContext): string {
         "test:unit": "bun test shared/src/ backend/src/ tests/unit/",
         "test:image": "bun test tests/image/",
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
+        "sync:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/sync-drift.ts",
         typecheck: "bunx tsc --noEmit -p shared && bunx tsc --noEmit -p backend && bunx tsc --noEmit -p .",
         build: "bun run lint && bun run typecheck && bun run build:no-lint",
         "build:no-lint": "bun run build:shared && bun run build:backend",

package/package.json

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