@norskvideo/ctl-dev-kit 0.1.4 → 0.1.6

package/build/flake.nix

@@ -1,7 +1,8 @@
 # Product build + dev shell — single-sourced in @norskvideo/ctl-dev-kit and
 # copied verbatim into each split product repo (nix needs a flake.nix at the repo
 # root for `nix develop`; it can't pull one from an npm package at CI bootstrap).
-# The copy is drift-gated (Workstream I), same model as the fenced CLAUDE.md core.
+# The copy is to be drift-gated (Workstream I; not yet enforced), same model as
+# the fenced CLAUDE.md core.
 #
 # Three shells:
 #   nix develop         -> build tools (bun, cargo/rustc, git) + the pinned

package/conventions/CLAUDE.core.md

@@ -2,11 +2,11 @@
 <!--
   This block is the SHARED conventions core, single-sourced in
   @norskvideo/ctl-dev-kit (conventions/CLAUDE.core.md). It is copied verbatim
-  into each product repo's CLAUDE.md between these fenced markers, and a
-  drift-check gate (Workstream I) fails CI if a copy diverges from the dev-kit's
-  version. Do NOT hand-edit a copy — edit the dev-kit source and re-sync. The
-  per-product tail (this product's build, iterate loop, gotchas) lives OUTSIDE
-  the markers and is yours to own.
+  into each product repo's CLAUDE.md between these fenced markers. A drift-check
+  gate is planned (Workstream I) to fail CI if a copy diverges from the dev-kit's
+  version — until it lands, do NOT hand-edit a copy: edit the dev-kit source and
+  re-sync. The per-product tail (this product's build, iterate loop, gotchas)
+  lives OUTSIDE the markers and is yours to own.
 
   It is copied (not `@import`ed) on purpose: CLAUDE.md's value is being read
   verbatim by a human on GitHub with no tooling, and an @import shows a human a

package/conventions/check-drift.ts

@@ -0,0 +1,94 @@
+// Workstream I drift gate. Fails a product repo whose forced copies of the
+// shared conventions have diverged from this dev-kit's canonical source:
+//   - the fenced `ctl-shared-conventions v1` core inside its CLAUDE.md, and
+//   - its root flake.nix.
+//
+// Both are copied verbatim (not @import-ed / not a dep) so a human reads them on
+// GitHub with no tooling — which is exactly where drift starts. The gate makes
+// "single-sourced in @norskvideo/ctl-dev-kit" true: a product runs it in CI
+// against the dev-kit version it has installed, so bumping the pinned dev-kit
+// forces a re-sync. Canonical bytes are the files shipped alongside this script
+// (conventions/CLAUDE.core.md + build/flake.nix), resolved package-relative so
+// they work both workspace-symlinked and installed from the published tarball.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DriftReport {
+  ok: boolean;
+  problems: string[];
+}
+
+const BEGIN = "<!-- BEGIN ctl-shared-conventions v1 -->";
+const END = "<!-- END ctl-shared-conventions v1 -->";
+
+const RESYNC = "Edit the dev-kit source and re-sync — never hand-edit the copy.";
+
+// First line that differs, so the failure names the drift instead of dumping the
+// whole block. Compared line-wise; the byte check is the substring test above.
+function firstDiffLine(actual: string, expected: string): string {
+  const a = actual.split("\n");
+  const e = expected.split("\n");
+  for (let i = 0; i < Math.max(a.length, e.length); i++) {
+    if (a[i] !== e[i]) {
+      return `line ${i + 1}: expected ${JSON.stringify(e[i] ?? "<missing>")}, found ${JSON.stringify(a[i] ?? "<missing>")}`;
+    }
+  }
+  return "content differs";
+}
+
+function coreProblem(claude: string, canonicalCore: string): string | undefined {
+  if (claude.includes(canonicalCore)) return undefined;
+
+  const begin = claude.indexOf(BEGIN);
+  const end = claude.indexOf(END);
+  if (begin === -1 || end === -1) {
+    return `CLAUDE.md is missing the '${BEGIN}' / '${END}' marker block. Copy conventions/CLAUDE.core.md from @norskvideo/ctl-dev-kit verbatim between the markers.`;
+  }
+  const region = claude.slice(begin, end + END.length);
+  return `CLAUDE.md fenced core has drifted from @norskvideo/ctl-dev-kit conventions/CLAUDE.core.md (${firstDiffLine(region, canonicalCore.trimEnd())}). ${RESYNC}`;
+}
+
+export function checkDrift(repoRoot: string, canonical: { core: string; flake: string }): DriftReport {
+  const problems: string[] = [];
+
+  const claudePath = join(repoRoot, "CLAUDE.md");
+  if (!existsSync(claudePath)) {
+    problems.push(`CLAUDE.md not found at repo root (${claudePath}). It must embed the ctl-shared-conventions core.`);
+  } else {
+    const problem = coreProblem(readFileSync(claudePath, "utf8"), canonical.core);
+    if (problem) problems.push(problem);
+  }
+
+  const flakePath = join(repoRoot, "flake.nix");
+  if (!existsSync(flakePath)) {
+    problems.push(
+      `flake.nix not found at repo root (${flakePath}). It is copied verbatim from @norskvideo/ctl-dev-kit build/flake.nix.`,
+    );
+  } else {
+    const flake = readFileSync(flakePath, "utf8");
+    if (flake !== canonical.flake) {
+      problems.push(
+        `flake.nix has drifted from @norskvideo/ctl-dev-kit build/flake.nix (${firstDiffLine(flake, canonical.flake)}). ${RESYNC}`,
+      );
+    }
+  }
+
+  return { ok: problems.length === 0, problems };
+}
+
+if (import.meta.main) {
+  const repoRoot = process.argv[2] ?? process.cwd();
+  const canonical = {
+    core: readFileSync(join(import.meta.dir, "CLAUDE.core.md"), "utf8"),
+    flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
+  };
+  const report = checkDrift(repoRoot, canonical);
+  if (report.ok) {
+    console.log("drift-check: CLAUDE.md core + flake.nix match @norskvideo/ctl-dev-kit.");
+    process.exit(0);
+  }
+  console.error(
+    `drift-check FAILED (${report.problems.length} problem(s)):\n${report.problems.map((p) => `  - ${p}`).join("\n\n")}`,
+  );
+  process.exit(1);
+}

package/package.json

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