@ingram-tech/nk-dev 0.9.0 → 0.11.0

package/README.md

@@ -3,7 +3,8 @@
 The nextkit **dev toolchain in one package**. Everything a site needs at
 development time — and nothing that ships to production — lives here:
 
-- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `ast-grep` / `check` / `type-check` / `test` / `build`, plus `nk doctor`);
+- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `ast-grep` / `migrations` / `check` / `type-check` / `test` / `build`, plus
+  `nk doctor`);
 - the shared **oxlint + oxfmt**, **TypeScript**, and **Vitest** config;
 - **knip** (unused dependency / export / file detection), bundled and run by `nk check`;
 - the **oxfmt format-on-commit** git hook (`nextkit-format-staged`);
@@ -80,7 +81,8 @@ tsc), so versions stay under each site's control — nk just orchestrates.
   skips files that already exist.
 - **`nk doctor [--fix]`** — report drift from the canonical nk-dev toolchain
   (superseded deps, config `extends`, package.json scripts, the agent-guide
-  import, a stale `.prettierignore`); `--fix` applies the auto-fixable findings.
+  import, a stale `.prettierignore`, an unsealed migration chain and the DDL in
+  it drizzle can't model); `--fix` applies the auto-fixable findings.
 - **`nk dev`** — start the Next dev server on the golden-path local database
   (see [`db-package.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/db-package.md)):
   - **PGlite** — if `@ingram-tech/nk-db`'s `nk-pglite-dev` bin resolves, hand off
@@ -92,6 +94,14 @@ tsc), so versions stay under each site's control — nk just orchestrates.
   generated (drizzle migrations, `pg_dump` baselines, pglite fixtures).
 - **`nk lint`** — `oxlint`.
 - **`nk knip`** — `knip` (unused dependencies / exports / files).
+- **`nk migrations [--check|--reseal|--ddl]`** — guard the `drizzle/` migration
+  chain, with no database involved. Verifies each file against the hashes in
+  `drizzle/_seal.json` and seals newly generated ones; `--check` verifies
+  without writing (what `nk check` runs); `--reseal` rewrites every hash for a
+  deliberate squash; `--ddl` lists the migrations carrying DDL drizzle's
+  snapshot can't model. Details in
+  [`db-package.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/db-package.md#the-seal-applied-migrations-are-immutable).
+  A no-op on sites without a migration journal.
 - **`nk ast-grep [...]`** — structural search & rewrite of TS/TSX by AST pattern,
   via the vendored [ast-grep](https://ast-grep.github.io) (args passed through to
   it). For large mechanical refactors — import rewrites, API renames, call-shape
@@ -99,8 +109,8 @@ tsc), so versions stay under each site's control — nk just orchestrates.
   apply → `nk format` + `nk type-check`) and its syntactic-not-semantic limits
   live in the codemod skill, `skills/ts-codemod.md`.
 - **`nk check`** — `oxlint` + `oxfmt --check` + `knip` (only when the repo has a
-  knip config) + the agent-guide import gate. The CI gate; runs every checker and
-  reports them all before failing.
+  knip config) + the agent-guide import gate + the migration seal. The CI gate;
+  runs every checker and reports them all before failing.
 - **`nk type-check`** — `next typegen && tsc --noEmit`.
 - **`nk test [...]`** — `vitest run`, extra args passed through.
 - **`nk build [...]`** — `next build`, extra args passed through.

package/bin/nk.js

@@ -5,7 +5,8 @@ import { doctor } from "../lib/doctor.js";
 import { format } from "../lib/format.js";
 import { init } from "../lib/init.js";
 import { knip } from "../lib/knip.js";
-import { build, check, lint, test, typeCheck } from "../lib/passthrough.js";
+import { migrations } from "../lib/migrations.js";
+import { build, check, clean, lint, test, typeCheck } from "../lib/passthrough.js";
 
 const USAGE = `nk — the nextkit CLI
 
@@ -22,12 +23,20 @@ Commands:
   format [--check]    Format code with oxfmt. --check verifies without writing.
   lint [...]          Lint with oxlint (extra args passed through, e.g. --fix).
   knip                Find unused dependencies / exports / files with knip.
+  migrations [...]    Guard the drizzle migration chain: verify that no applied
+                      migration's bytes changed, and seal newly generated ones.
+                      --check verifies without writing (CI); --reseal rewrites
+                      every hash (a deliberate squash); --ddl lists the DDL
+                      drizzle's snapshot cannot model.
   ast-grep [...]      Structural search & rewrite of TS/TSX by AST pattern
                       (vendored ast-grep; args passed through). For large
                       mechanical refactors — see the codemod skill.
   check               The CI gate: lint + format verify + knip (when configured)
-                      + the agent-guide import gate.
-  type-check          next typegen && tsc --noEmit.
+                      + the agent-guide import gate + the migration seal.
+  type-check          next typegen && tsc --noEmit. Recovers automatically when
+                      generated types are damaged (e.g. a killed dev server).
+  clean               Remove regenerable build artifacts: Next's generated
+                      types and TypeScript incremental caches.
   test [...]          vitest run (extra args passed through).
   build [...]         next build (extra args passed through).
 
@@ -55,6 +64,9 @@ switch (cmd) {
 	case "knip":
 		knip(rest);
 		break;
+	case "migrations":
+		migrations(rest);
+		break;
 	case "ast-grep":
 		astGrep(rest);
 		break;
@@ -64,6 +76,9 @@ switch (cmd) {
 	case "type-check":
 		typeCheck();
 		break;
+	case "clean":
+		clean();
+		break;
 	case "test":
 		test(rest);
 		break;

package/guide.md

@@ -83,6 +83,33 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
   transaction, before commit. A blind move that touches nothing (an RLS mask, a
   wrong `where`) otherwise reports success, and the drop of the source columns
   in the same migration makes it unrecoverable.
+- **Never edit a migration that has been applied.** The runner records
+  `sha256(file)`, so the bytes are history: editing one drifts every database
+  that already ran it, and drizzle never looks at the file again to notice.
+  Express the change as a **new** migration. `drizzle/_seal.json` pins the
+  hashes and `nk check` fails on a mismatch — if it does, `git checkout` the
+  file rather than resealing. After generating a migration, run **`nk
+  migrations`** and commit `_seal.json` in the same commit as the `.sql`.
+  `nk migrations --reseal` exists only for a deliberate squash, which also
+  requires reconciling every database with `nk-pg-migrate --baseline`.
+- **A clean `db:generate` does not mean the chain matches the database.**
+  drizzle diffs `schema.ts` against `meta/*_snapshot.json`, never against the
+  `.sql` files, and the snapshot can't model functions, triggers, `DEFERRABLE`
+  constraints, grants or roles. Anything regenerated from `schema.ts` drops
+  those clauses silently. `nk migrations --ddl` lists which migrations carry
+  them; verify against a real database before trusting a regenerated chain.
+- **Never hand-append unmodelled DDL to a generated migration.** A generated
+  file must stay exactly what `drizzle-kit generate` produced, or the snapshot
+  becomes an active lie about a file drizzle believes it owns — and the next
+  regenerate re-emits those objects without your clauses. Put functions,
+  triggers, `DEFERRABLE`, grants and roles in `drizzle-kit generate --custom`
+  migrations instead.
+- **Merging two branches that both added migrations? Check the journal.**
+  drizzle applies files by `when > max(created_at)`, so a migration whose `when`
+  lands below one already applied is skipped silently and forever.
+  `nk-pg-migrate` refuses to run in that state (`MigrationOrderError`); fix it
+  by raising the stranded entry's `when` in `meta/_journal.json` — never by
+  editing the `.sql`, which would break the hash every database recorded.
 - **`drizzle-kit` is GENERATE-ONLY — it must never apply schema.** Use it for
   `drizzle-kit generate` (and `generate --custom` for a package-owned/raw SQL
   migration). Applying is always **`nk-pg-migrate`** (the bin from

package/lib/artifacts.js

@@ -0,0 +1,105 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Directories a tool regenerates from source, and which `tsconfig.json`
+ * typically feeds back into `tsc` (Next's typed-routes output is in `include`).
+ *
+ * That round trip is what makes them worth tracking: a killed `next dev` can
+ * leave `.next/dev/types/validator.ts` truncated mid-write, and `next typegen`
+ * does **not** repair it, so `tsc` keeps reporting a syntax error inside
+ * generated code until the directory is removed. The error points at `.next/`,
+ * so the natural reflex is to hunt a type error in `src/` that doesn't exist.
+ */
+const GENERATED_DIRECTORIES = [
+	{ path: ".next/dev/types", owner: "next typegen", typeCheckInput: true },
+	{ path: ".next/types", owner: "next typegen", typeCheckInput: true },
+];
+
+/** Prefixes (posix-normalised) that `tsc` error locations may fall inside. */
+export const TYPE_CHECK_INPUT_PREFIXES = GENERATED_DIRECTORIES.filter(
+	(entry) => entry.typeCheckInput,
+).map((entry) => entry.path);
+
+/**
+ * Every generated artifact present in `cwd`. Incremental-build caches are
+ * discovered rather than hardcoded, since `tsBuildInfoFile` renames them and a
+ * repo can carry several (`tsconfig.tsbuildinfo`, `tsconfig.slice.tsbuildinfo`).
+ *
+ * Deleting any of these is safe by construction: the owning tool rebuilds it.
+ */
+export function listGeneratedArtifacts(cwd = process.cwd()) {
+	const present = GENERATED_DIRECTORIES.filter((entry) =>
+		existsSync(join(cwd, entry.path)),
+	);
+
+	let buildInfo = [];
+	try {
+		buildInfo = readdirSync(cwd)
+			.filter((name) => name.endsWith(".tsbuildinfo"))
+			.map((name) => ({ path: name, owner: "tsc", typeCheckInput: false }));
+	} catch {
+		// An unreadable cwd is the caller's problem, not this helper's.
+	}
+
+	return [...present, ...buildInfo];
+}
+
+/**
+ * Remove generated artifacts and return the paths actually deleted. Missing
+ * paths are skipped rather than reported, so this is idempotent.
+ */
+export function cleanGeneratedArtifacts(cwd = process.cwd()) {
+	const removed = [];
+	for (const entry of listGeneratedArtifacts(cwd)) {
+		rmSync(join(cwd, entry.path), { recursive: true, force: true });
+		removed.push(entry.path);
+	}
+	return removed;
+}
+
+// Colour codes only (ESC [ … m). ESC is built from its code point rather
+// than written inline: matching it is the entire point of stripping colour, but
+// a control character inside a regex literal trips `no-control-regex`.
+const ANSI = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;]*m`, "g");
+
+/**
+ * `tsc` error headers, in both layouts: plain (piped / `--pretty false`) and
+ * pretty (a TTY, or `--pretty`).
+ */
+const ERROR_LOCATIONS = [
+	/^(.+?)\((\d+),(\d+)\): (?:error|warning) TS\d+/,
+	/^(.+?):(\d+):(\d+) - (?:error|warning) TS\d+/,
+];
+
+/** Unique file paths `tsc` reported errors in, posix-normalised. */
+export function errorFiles(output) {
+	const files = new Set();
+	for (const rawLine of String(output).split(/\r?\n/)) {
+		const line = rawLine.replace(ANSI, "");
+		for (const pattern of ERROR_LOCATIONS) {
+			const match = line.match(pattern);
+			if (!match?.[1]) continue;
+			files.add(match[1].trim().replaceAll("\\", "/").replace(/^\.\//, ""));
+			break;
+		}
+	}
+	return [...files];
+}
+
+/**
+ * Whether every error `tsc` reported sits inside generated type output — the
+ * signature of a damaged artifact rather than a source defect.
+ *
+ * Deliberately "every", not "any": a run that mixes generated and `src/` errors
+ * has real work in it, and cleaning would neither fix nor excuse those.
+ */
+export function onlyGeneratedTypeErrors(output) {
+	const files = errorFiles(output);
+	if (files.length === 0) return false;
+	return files.every((file) =>
+		TYPE_CHECK_INPUT_PREFIXES.some(
+			(prefix) => file === prefix || file.startsWith(`${prefix}/`),
+		),
+	);
+}

package/lib/doctor.js

@@ -1,6 +1,15 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { SUPERSEDED_DEPS } from "./drift.js";
+import {
+	SEAL_FILE,
+	migrationsFolder,
+	readChain,
+	readSeal,
+	summarizeKinds,
+	unmodelledDdl,
+	writeSeal,
+} from "./migrations.js";
 
 // The canonical script → command mapping for a site on the nk-dev toolchain.
 // The key is matched loosely (`type-check` and `typecheck` are both accepted);
@@ -257,6 +266,62 @@ export function findings(cwd) {
 		});
 	}
 
+	// 9. The migration chain is sealed, and its unmodelled DDL is declared.
+	out.push(...migrationFindings(cwd));
+
+	return out;
+}
+
+/**
+ * Findings over a `drizzle/` chain. Silent on repos without one.
+ *
+ * The seal finding is the cheap half of migration safety: applied migrations
+ * are immutable, and nothing in drizzle notices when one is edited.
+ *
+ * The unmodelled-DDL finding is the honest half. `drizzle-kit generate` diffs
+ * `schema.ts` against `meta/*_snapshot.json`, so any DDL the snapshot can't
+ * model — functions, triggers, `DEFERRABLE` constraints, grants, roles — is
+ * outside the diff basis entirely. A chain carrying it can drift arbitrarily
+ * far from the database while `db:generate` still reports no changes, and
+ * anything regenerated from `schema.ts` drops it. That is a real property of
+ * the repo, so `nk doctor` states it rather than leaving it to be rediscovered.
+ */
+function migrationFindings(cwd) {
+	const out = [];
+	const folder = migrationsFolder(cwd);
+	let chain;
+	try {
+		chain = readChain(cwd, folder);
+	} catch (err) {
+		return [
+			{ id: "migrations:broken-chain", level: "error", message: err.message },
+		];
+	}
+	if (chain === null || chain.length === 0) return out;
+
+	if (readSeal(cwd, folder) === null) {
+		out.push({
+			id: "migrations:unsealed",
+			level: "warn",
+			message: `${chain.length} migration(s) with no ${folder}/${SEAL_FILE} — an edit to an already-applied migration would go unnoticed`,
+			fix: (dir) => {
+				const f = migrationsFolder(dir);
+				writeSeal(dir, f, readChain(dir, f));
+				return `sealed ${chain.length} migration(s) in ${f}/${SEAL_FILE}`;
+			},
+		});
+	}
+
+	const inventory = unmodelledDdl(cwd, folder);
+	if (inventory.length > 0) {
+		const kinds = summarizeKinds(inventory);
+		out.push({
+			id: "migrations:unmodelled-ddl",
+			level: "warn",
+			message: `${inventory.length} of ${chain.length} migration(s) carry DDL drizzle's snapshot cannot model (${kinds.join(", ")}) — \`db:generate\` reporting "no changes" does not mean the chain reproduces the database, and regenerating from schema.ts drops it. Run \`nk migrations --ddl\` for the per-file list.`,
+		});
+	}
+
 	return out;
 }
 
@@ -264,7 +329,8 @@ export function findings(cwd) {
  * `nk doctor [--fix]` — report drift from the canonical nk-dev model (scripts,
  * dependencies, oxlint/tsconfig extends, the CLAUDE.md guide import, stale knip
  * ignores, forbidden schema-applying drizzle-kit scripts, a dead
- * .prettierignore). With `--fix`, apply every auto-fixable finding, then remind
+ * .prettierignore, an unsealed or unmodelled-DDL-carrying migration chain).
+ * With `--fix`, apply every auto-fixable finding, then remind
  * to reinstall.
  */
 export function doctor(args = []) {

package/lib/migrations.js

@@ -0,0 +1,354 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Two guards over a `drizzle/` migration chain, both of which exist because
+// `drizzle-kit generate` diffs `schema.ts` against `meta/*_snapshot.json` and
+// NEVER against the `.sql` files:
+//
+//   1. THE SEAL. Once a migration has been applied anywhere, its bytes are
+//      history — the runner records `sha256(file)` in the journal table, so
+//      editing the file (a formatter sweep, a "quick fix" to a generated
+//      migration) permanently drifts every database that already ran it. There
+//      is nothing in drizzle that notices. {@link verifySeal} pins each file's
+//      hash in a committed `_seal.json`, so the edit shows up as a failed check
+//      in the PR that made it instead of as a confusing `already exists` on the
+//      next deploy.
+//
+//   2. THE UNMODELLED-DDL INVENTORY. Functions, triggers, `DEFERRABLE`
+//      constraints, grants and roles are not in drizzle's snapshot model. Once
+//      a migration carries them, the snapshot is a permanently partial view of
+//      the schema: `db:generate` reports "nothing to migrate" no matter how far
+//      the chain has drifted from the database, and anything regenerated from
+//      `schema.ts` (notably a squash) silently drops them.
+//      {@link unmodelledDdl} turns that from tribal knowledge into a list.
+//
+// Both are deliberately database-free: they run in CI, in a pre-commit hook and
+// on a laptop with no `DATABASE_URL`. Proving the chain actually reproduces the
+// live schema needs a catalog diff against a real database, which is a
+// different (and much larger) tool.
+
+/** Name of the seal file, written inside the migrations folder. */
+export const SEAL_FILE = "_seal.json";
+
+const SEAL_COMMENT =
+	"sha256 of each migration file at the time it was sealed. Applied migrations are immutable: if a hash here stops matching, the file was edited after it ran and every database that already applied it has drifted. Regenerate with `nk migrations --reseal` ONLY as part of a deliberate squash.";
+
+/**
+ * The migrations folder for a repo. Honours `out:` in a drizzle config when one
+ * is present (matched textually — we are not loading the site's TS config just
+ * to read one string), else drizzle's `drizzle` default.
+ */
+export function migrationsFolder(cwd = process.cwd()) {
+	for (const name of [
+		"drizzle.config.ts",
+		"drizzle.config.js",
+		"drizzle.config.mjs",
+	]) {
+		const path = resolve(cwd, name);
+		if (!existsSync(path)) continue;
+		const match = /\bout\s*:\s*["'`]([^"'`]+)["'`]/.exec(
+			readFileSync(path, "utf8"),
+		);
+		if (match?.[1]) return match[1];
+	}
+	return "drizzle";
+}
+
+const journalPathFor = (cwd, folder) => resolve(cwd, folder, "meta", "_journal.json");
+
+/**
+ * The migration chain as `{ tag, hash }`, in journal order. `hash` is
+ * `sha256(rawFile)` — the exact value drizzle records in `__drizzle_migrations`,
+ * so a mismatch here is a mismatch there.
+ *
+ * Returns null when the repo has no journal (not a drizzle site — nothing to
+ * guard). Throws when the journal names a file that doesn't exist, which is
+ * itself a broken chain.
+ */
+export function readChain(cwd = process.cwd(), folder = migrationsFolder(cwd)) {
+	const journalPath = journalPathFor(cwd, folder);
+	if (!existsSync(journalPath)) return null;
+	const journal = JSON.parse(readFileSync(journalPath, "utf8"));
+	const entries = Array.isArray(journal?.entries) ? journal.entries : [];
+	return entries.map((entry) => {
+		const sqlPath = resolve(cwd, folder, `${entry.tag}.sql`);
+		if (!existsSync(sqlPath)) {
+			throw new Error(
+				`nk migrations: journal entry "${entry.tag}" has no ${folder}/${entry.tag}.sql`,
+			);
+		}
+		const sql = readFileSync(sqlPath, "utf8");
+		return {
+			tag: entry.tag,
+			hash: createHash("sha256").update(sql).digest("hex"),
+			sql,
+		};
+	});
+}
+
+/** The committed seal, or an empty one when the repo hasn't sealed yet. */
+export function readSeal(cwd = process.cwd(), folder = migrationsFolder(cwd)) {
+	const path = resolve(cwd, folder, SEAL_FILE);
+	if (!existsSync(path)) return null;
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	return parsed?.migrations && typeof parsed.migrations === "object"
+		? parsed.migrations
+		: {};
+}
+
+/** Write the seal for `chain`, in journal order (stable diffs). */
+export function writeSeal(cwd, folder, chain) {
+	const migrations = {};
+	for (const m of chain) migrations[m.tag] = m.hash;
+	writeFileSync(
+		resolve(cwd, folder, SEAL_FILE),
+		`${JSON.stringify({ $comment: SEAL_COMMENT, migrations }, null, "\t")}\n`,
+	);
+}
+
+/**
+ * Compare the chain on disk to the committed seal.
+ *
+ * - `changed` — sealed migrations whose bytes moved. Always a defect: those
+ *   files have already run somewhere.
+ * - `dropped` — sealed migrations no longer in the journal. Normal during a
+ *   squash, a defect at any other time.
+ * - `unsealed` — migrations with no seal entry yet (newly generated).
+ */
+export function verifySeal(cwd = process.cwd(), folder = migrationsFolder(cwd)) {
+	const chain = readChain(cwd, folder);
+	if (chain === null) return null;
+	const sealed = readSeal(cwd, folder);
+	if (sealed === null) {
+		return { chain, sealedYet: false, changed: [], dropped: [], unsealed: chain };
+	}
+	const changed = [];
+	const unsealed = [];
+	for (const m of chain) {
+		const expected = sealed[m.tag];
+		if (expected === undefined) unsealed.push(m);
+		else if (expected !== m.hash) changed.push({ ...m, sealed: expected });
+	}
+	const tags = new Set(chain.map((m) => m.tag));
+	const dropped = Object.keys(sealed).filter((tag) => !tags.has(tag));
+	return { chain, sealedYet: true, changed, dropped, unsealed };
+}
+
+// DDL that drizzle's snapshot model does not represent. Each entry is
+// `[kind, pattern]`, matched against SQL with comments, string literals and
+// dollar-quoted bodies stripped, so a mention inside a function body or a
+// `-- create trigger` comment doesn't count.
+const UNMODELLED = [
+	["function", /\bcreate\s+(?:or\s+replace\s+)?(?:function|procedure)\b/i],
+	["trigger", /\bcreate\s+(?:constraint\s+|event\s+)?trigger\b/i],
+	["deferrable", /\bdeferrable\b/i],
+	["grant", /\b(?:grant|revoke)\b/i],
+	["role", /\b(?:create|alter|drop)\s+role\b/i],
+	["extension", /\bcreate\s+extension\b/i],
+	["materialized-view", /\bcreate\s+materialized\s+view\b/i],
+	["rule", /\bcreate\s+(?:or\s+replace\s+)?rule\b/i],
+	["do-block", /(?:^|;|\n)\s*do\s+\$/i],
+];
+
+/**
+ * Blank out anything that isn't executable DDL text: dollar-quoted bodies (a
+ * function body full of SQL keywords), block and line comments, single-quoted
+ * literals and double-quoted identifiers. Replaced with spaces rather than
+ * removed so nothing accidentally joins into a new keyword.
+ */
+function stripNonDdl(sql) {
+	const blank = (m) => " ".repeat(m.length);
+	return (
+		sql
+			// A dollar-quoted body collapses to a bare `$$` rather than to spaces:
+			// the body's contents are not statements, but the opener still has to be
+			// visible so `do $$ ... $$` is recognisable as an anonymous block.
+			.replace(/\$([A-Za-z_]\w*)?\$[\s\S]*?\$\1?\$/g, " $$$$ ")
+			.replace(/\/\*[\s\S]*?\*\//g, blank)
+			.replace(/--[^\n]*/g, blank)
+			.replace(/'(?:[^']|'')*'/g, blank)
+			.replace(/"(?:[^"]|"")*"/g, blank)
+	);
+}
+
+/** The unmodelled-DDL kinds present in one migration's SQL. */
+export function unmodelledKinds(sql) {
+	const stripped = stripNonDdl(sql);
+	return UNMODELLED.filter(([, pattern]) => pattern.test(stripped)).map(
+		([kind]) => kind,
+	);
+}
+
+/**
+ * Per-file inventory of DDL drizzle can't model: `[{ tag, kinds }]`, only for
+ * files that carry some. Empty when the chain is purely generated output (the
+ * only case in which `db:generate` reporting "no changes" actually means the
+ * chain reproduces `schema.ts`).
+ */
+export function unmodelledDdl(cwd = process.cwd(), folder = migrationsFolder(cwd)) {
+	const chain = readChain(cwd, folder);
+	if (chain === null) return [];
+	return chain
+		.map((m) => ({ tag: m.tag, kinds: unmodelledKinds(m.sql) }))
+		.filter((m) => m.kinds.length > 0);
+}
+
+/** Distinct kinds across a whole inventory, for a one-line summary. */
+export function summarizeKinds(inventory) {
+	return [...new Set(inventory.flatMap((m) => m.kinds))].sort();
+}
+
+const short = (hash) => hash.slice(0, 12);
+
+/**
+ * The `nk check` gate: `{ ok, reason }`, non-exiting. `ok` on a repo with no
+ * journal (not every site has a database) and on a chain that matches its seal.
+ */
+export function checkSeal(cwd = process.cwd()) {
+	const folder = migrationsFolder(cwd);
+	let state;
+	try {
+		state = verifySeal(cwd, folder);
+	} catch (err) {
+		return { ok: false, reason: err.message };
+	}
+	if (state === null) return { ok: true };
+	const problems = [
+		...state.changed.map(
+			(m) =>
+				`${m.tag} changed after it was sealed (${short(m.sealed)} → ${short(m.hash)})`,
+		),
+		...state.dropped.map(
+			(tag) => `${tag} was sealed but is no longer in the journal`,
+		),
+		...state.unsealed.map((m) => `${m.tag} is unsealed`),
+	];
+	if (problems.length === 0) return { ok: true };
+	return {
+		ok: false,
+		reason: `migration chain does not match ${folder}/${SEAL_FILE} — ${problems.join("; ")}`,
+	};
+}
+
+/**
+ * `nk migrations [--check|--reseal|--ddl]` — guard the migration chain.
+ *
+ * Default: verify the seal, then seal anything newly generated and write the
+ * file. `--check` verifies without writing (the CI shape: an unsealed migration
+ * is a failure, because the seal must land in the same commit as the
+ * migration). `--reseal` rewrites every hash — the deliberate squash escape
+ * hatch, whose effect is visible in the diff. `--ddl` prints the
+ * unmodelled-DDL inventory.
+ */
+export function migrations(args = []) {
+	const cwd = process.cwd();
+	const folder = migrationsFolder(cwd);
+	const checkOnly = args.includes("--check");
+
+	let state;
+	try {
+		state = verifySeal(cwd, folder);
+	} catch (err) {
+		console.error(`nk migrations: ${err.message}`);
+		process.exit(1);
+	}
+	if (state === null) {
+		if (!checkOnly) console.log(`nk migrations: no ${folder}/meta/_journal.json.`);
+		process.exit(0);
+	}
+
+	if (args.includes("--ddl")) {
+		printDdl(cwd, folder);
+		process.exit(0);
+	}
+
+	if (args.includes("--reseal")) {
+		writeSeal(cwd, folder, state.chain);
+		console.log(
+			`nk migrations: resealed ${state.chain.length} migration(s) in ${folder}/${SEAL_FILE}.`,
+		);
+		for (const m of state.changed) {
+			console.log(`  ! ${m.tag}: ${short(m.sealed)} → ${short(m.hash)}`);
+		}
+		for (const tag of state.dropped) console.log(`  – ${tag} (dropped)`);
+		console.log(
+			"\n  Every database that already ran a changed or dropped migration must be reconciled (`nk-pg-migrate --baseline`) and verified against the new chain before this ships.",
+		);
+		process.exit(0);
+	}
+
+	const broken = state.changed.length > 0 || state.dropped.length > 0;
+	for (const m of state.changed) {
+		console.error(
+			`nk migrations: ✗ ${m.tag} changed after it was sealed (${short(m.sealed)} → ${short(m.hash)})`,
+		);
+	}
+	for (const tag of state.dropped) {
+		console.error(
+			`nk migrations: ✗ ${tag} was sealed but is no longer in the journal`,
+		);
+	}
+	if (broken) {
+		console.error(
+			"\n  An applied migration's bytes are history: every database that ran it recorded that hash. Restore the file (`git checkout`) and express the change as a NEW migration.",
+		);
+		console.error(
+			"  If this is a deliberate squash, run `nk migrations --reseal` and reconcile each database with `nk-pg-migrate --baseline`.",
+		);
+		process.exit(1);
+	}
+
+	if (checkOnly) {
+		if (state.unsealed.length > 0) {
+			console.error(
+				`nk migrations: ✗ ${state.unsealed.length} unsealed migration(s): ${state.unsealed.map((m) => m.tag).join(", ")}`,
+			);
+			console.error(
+				`  → run \`nk migrations\` and commit ${folder}/${SEAL_FILE} alongside the migration.`,
+			);
+			process.exit(1);
+		}
+		console.log(
+			`nk migrations: ✓ ${state.chain.length} migration(s) match the seal.`,
+		);
+		process.exit(0);
+	}
+
+	if (state.unsealed.length === 0 && state.sealedYet) {
+		console.log(
+			`nk migrations: ✓ ${state.chain.length} migration(s) match the seal.`,
+		);
+		process.exit(0);
+	}
+	writeSeal(cwd, folder, state.chain);
+	console.log(
+		`nk migrations: sealed ${state.unsealed.length} new migration(s) — commit ${folder}/${SEAL_FILE}.`,
+	);
+	for (const m of state.unsealed) console.log(`  + ${m.tag}`);
+	process.exit(0);
+}
+
+function printDdl(cwd, folder) {
+	const inventory = unmodelledDdl(cwd, folder);
+	if (inventory.length === 0) {
+		console.log(
+			"nk migrations: no DDL outside drizzle's snapshot model — `db:generate` sees the whole schema.",
+		);
+		return;
+	}
+	console.log(
+		`nk migrations: ${inventory.length} migration(s) carry DDL drizzle's snapshot cannot model:\n`,
+	);
+	for (const m of inventory) console.log(`  ${m.tag}  ${m.kinds.join(", ")}`);
+	console.log(
+		"\n  drizzle diffs schema.ts against meta/*_snapshot.json, so none of this is in the diff basis:",
+	);
+	console.log(
+		"  `db:generate` reporting no changes does NOT mean the chain reproduces the database, and anything",
+	);
+	console.log(
+		"  regenerated from schema.ts (a squash above all) drops these clauses silently. Verify against a real",
+	);
+	console.log("  database before trusting a regenerated chain.");
+}

package/lib/oxlint-plugins/index.js

@@ -7,7 +7,9 @@ import deferredCurrentTarget from "./deferred-current-target.js";
 import lucideIconSuffix from "./lucide-icon-suffix.js";
 import noCryptoRandomUuid from "./no-crypto-random-uuid.js";
 import noRedirectOnlyPage from "./no-redirect-only-page.js";
+import noRedundantNodeCrypto from "./no-redundant-node-crypto.js";
 import redundantUseStateType from "./redundant-usestate-type.js";
+import satoriCss from "./satori-css.js";
 import tNoPositionalArgs from "./t-no-positional-args.js";
 import tRequiresValues from "./t-requires-values.js";
 
@@ -19,7 +21,9 @@ export default {
 		...lucideIconSuffix.rules,
 		...noCryptoRandomUuid.rules,
 		...noRedirectOnlyPage.rules,
+		...noRedundantNodeCrypto.rules,
 		...redundantUseStateType.rules,
+		...satoriCss.rules,
 		...tNoPositionalArgs.rules,
 		...tRequiresValues.rules,
 	},

package/lib/oxlint-plugins/no-redundant-node-crypto.js

@@ -0,0 +1,137 @@
+// nextkit oxlint JS plugin rule: don't import from `node:crypto` what is
+// already a global.
+//
+// Web Crypto is on `globalThis` in every runtime we ship to — Node (since 19,
+// and nk-dev's floor is 22), the browser, and every edge/worker runtime. So
+// `randomUUID`, `getRandomValues`, `subtle` and `webcrypto` are reachable as
+// `crypto.randomUUID()`, `crypto.getRandomValues()`, `crypto.subtle` and
+// `crypto` with no import at all.
+//
+// Importing them anyway costs something real: it pins the module to a Node-only
+// runtime for a function it would have had regardless. A component, a shared
+// helper or a route that could have run anywhere now can't, and the reason is
+// invisible at the call site — the code reads identically either way. Two of
+// these are not even different objects: `node:crypto`'s `subtle` and `webcrypto`
+// are the very same references as `globalThis.crypto.subtle` and
+// `globalThis.crypto`.
+//
+// nk-db already pays for this the hard way: its id codec is imported by Drizzle
+// schemas, client components and edge runtimes, so `id.ts` is held to an empty
+// import list by a test (`id.test.ts`, "isomorphic invariant") whose comment
+// names `node:crypto` for randomness as the tempting one. That invariant was
+// prose in one package; this rule is the mechanical version of it, fleet-wide.
+//
+// This is about the module boundary, not the algorithm. The rest of `node:crypto`
+// — `createHash`, `createHmac`, `createPrivateKey`, `randomBytes`,
+// `timingSafeEqual` — has no drop-in global (the Web Crypto equivalents live
+// under `crypto.subtle` and are async), so those imports are correct and this
+// rule leaves them alone. Trimming a redundant name off an import list is the
+// common fix; the import disappears entirely only when nothing else was on it.
+//
+// Deliberately not autofixable. Deleting the specifier is the easy half — the
+// call sites still have to become member expressions on the global, and a
+// default or namespace import named `crypto` (which shadows the global it is
+// standing in for) needs the whole file reread, not a mechanical edit.
+//
+// One case keeps the import: `node:crypto`'s `randomUUID` takes an options bag
+// (`randomUUID({ disableEntropyCache: true })`) that Web Crypto's does not. If
+// you need it, keep the import and say so:
+//
+//   // oxlint-disable-next-line nextkit/no-redundant-node-crypto -- needs disableEntropyCache
+//
+// Only static `import` is checked, matching every other rule in this plugin.
+// `require("node:crypto")` in a CommonJS script is out of scope.
+//
+// Note this overlaps by design with `nextkit/no-crypto-random-uuid`, which asks
+// a different question about the same call: that rule is about v4-versus-v7 for
+// a *stored id*, this one is about the module. A call site that justifiably
+// keeps v4 — a bearer token, a nonce — silences that rule and should still be
+// reaching for the global.
+
+const NODE_CRYPTO_MODULES = new Set(["crypto", "node:crypto"]);
+
+/** node:crypto exports that are already global, and what to reach for instead. */
+const REDUNDANT_EXPORTS = new Map([
+	["randomUUID", "crypto.randomUUID()"],
+	["getRandomValues", "crypto.getRandomValues()"],
+	["subtle", "crypto.subtle"],
+	["webcrypto", "crypto"],
+]);
+
+const noRedundantNodeCrypto = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description:
+				"Disallow importing node:crypto members that are already on the Web Crypto global",
+		},
+		messages: {
+			redundantImport:
+				"`{{name}}` from `{{module}}` is already global — use `{{replacement}}` and drop the import. Web Crypto is on globalThis in Node (>=19), the browser and every edge runtime, so importing it pins this module to Node for nothing. Keep the import only if you need a Node-specific signature, with `// oxlint-disable-next-line nextkit/no-redundant-node-crypto -- <reason>`.",
+			redundantMember:
+				"`{{local}}.{{name}}` is already global — use `{{replacement}}`. Web Crypto is on globalThis in Node (>=19), the browser and every edge runtime; reaching for it through the `{{module}}` namespace pins this module to Node for nothing.",
+		},
+	},
+	create(context) {
+		// Local names bound to the whole module (`import * as c` / `import c`),
+		// whose members we then check.
+		const namespaceNames = new Set();
+
+		return {
+			ImportDeclaration(node) {
+				const module = node.source.value;
+				if (!NODE_CRYPTO_MODULES.has(module)) return;
+
+				for (const specifier of node.specifiers) {
+					if (
+						specifier.type === "ImportNamespaceSpecifier" ||
+						specifier.type === "ImportDefaultSpecifier"
+					) {
+						namespaceNames.add(specifier.local.name);
+						continue;
+					}
+					if (specifier.type !== "ImportSpecifier") continue;
+					if (specifier.imported.type !== "Identifier") continue;
+
+					const name = specifier.imported.name;
+					const replacement = REDUNDANT_EXPORTS.get(name);
+					if (!replacement) continue;
+
+					context.report({
+						node: specifier,
+						messageId: "redundantImport",
+						data: { name, module, replacement },
+					});
+				}
+			},
+			// `nodeCrypto.subtle` where `nodeCrypto` is the imported module. The
+			// import itself can be legitimate (it may also carry `createHash`), so
+			// the redundant part is this access, not the declaration.
+			MemberExpression(node) {
+				if (node.computed) return;
+				if (node.object.type !== "Identifier") return;
+				if (!namespaceNames.has(node.object.name)) return;
+				if (node.property.type !== "Identifier") return;
+
+				const replacement = REDUNDANT_EXPORTS.get(node.property.name);
+				if (!replacement) return;
+
+				context.report({
+					node,
+					messageId: "redundantMember",
+					data: {
+						local: node.object.name,
+						name: node.property.name,
+						replacement,
+						module: "node:crypto",
+					},
+				});
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-redundant-node-crypto": noRedundantNodeCrypto },
+};

package/lib/oxlint-plugins/satori-css.js

@@ -0,0 +1,318 @@
+// nextkit oxlint JS plugin rule: validate inline styles in satori-rendered JSX.
+//
+// `next/og`'s `ImageResponse` types `style` as the full `React.CSSProperties`,
+// but satori implements a finite subset and **silently drops** everything else.
+// The image still renders, just wrong — which is why a render test can't catch
+// it: the PNG is valid, the shadow is simply missing. That gap is the whole
+// reason this rule exists (nk-seo README, "Open Graph image").
+//
+// Two classes of finding:
+//
+//   1. Style properties satori does not implement (`transition`, `cursor`,
+//      `backdropFilter`, the grid family, `zIndex`, `calc()`, …) — silent drops.
+//   2. The structural rules satori enforces at render time: a node with more
+//      than one child must set `display: flex` (or `none`), and text must not
+//      sit next to element siblings. These *do* throw at render; flagging them
+//      in-editor just moves the failure earlier.
+//
+// Scope: only files that are satori-bound — they import `next/og` (or
+// `@vercel/og`), or they are an `opengraph-image` / `twitter-image` file
+// convention. Sites using nk-seo's `ogImageResponse` write no satori JSX at all
+// and never trip this.
+//
+// The supported list is satori's documented one (https://github.com/vercel/satori#css)
+// plus the box-model properties yoga handles that the README's table omits. It
+// is deliberately generous: an over-wide allowlist only lowers the catch rate,
+// while a too-narrow one puts false positives into a config the whole fleet
+// inherits.
+
+/** https://github.com/vercel/satori#css, plus the yoga box-model properties. */
+const SUPPORTED = new Set([
+	// Display & position
+	"display",
+	"position",
+	"top",
+	"right",
+	"bottom",
+	"left",
+	"overflow",
+	"opacity",
+	"boxSizing",
+	"boxShadow",
+	"filter",
+	"clipPath",
+	"lineClamp",
+	"color",
+	// Box model
+	"margin",
+	"marginTop",
+	"marginRight",
+	"marginBottom",
+	"marginLeft",
+	"padding",
+	"paddingTop",
+	"paddingRight",
+	"paddingBottom",
+	"paddingLeft",
+	"width",
+	"height",
+	"minWidth",
+	"minHeight",
+	"maxWidth",
+	"maxHeight",
+	// Border
+	"border",
+	"borderTop",
+	"borderRight",
+	"borderBottom",
+	"borderLeft",
+	"borderWidth",
+	"borderTopWidth",
+	"borderRightWidth",
+	"borderBottomWidth",
+	"borderLeftWidth",
+	"borderStyle",
+	"borderTopStyle",
+	"borderRightStyle",
+	"borderBottomStyle",
+	"borderLeftStyle",
+	"borderColor",
+	"borderTopColor",
+	"borderRightColor",
+	"borderBottomColor",
+	"borderLeftColor",
+	"borderRadius",
+	"borderTopLeftRadius",
+	"borderTopRightRadius",
+	"borderBottomLeftRadius",
+	"borderBottomRightRadius",
+	// Flex
+	"flex",
+	"flexDirection",
+	"flexWrap",
+	"flexFlow",
+	"flexGrow",
+	"flexShrink",
+	"flexBasis",
+	"alignItems",
+	"alignContent",
+	"alignSelf",
+	"justifyContent",
+	"gap",
+	"rowGap",
+	"columnGap",
+	"order",
+	"aspectRatio",
+	// Font & text
+	"fontFamily",
+	"fontSize",
+	"fontWeight",
+	"fontStyle",
+	"tabSize",
+	"textAlign",
+	"textIndent",
+	"textTransform",
+	"textOverflow",
+	"textDecoration",
+	"textDecorationColor",
+	"textDecorationLine",
+	"textDecorationStyle",
+	"textShadow",
+	"textWrap",
+	"lineHeight",
+	"letterSpacing",
+	"whiteSpace",
+	"wordBreak",
+	// Background
+	"background",
+	"backgroundColor",
+	"backgroundImage",
+	"backgroundPosition",
+	"backgroundSize",
+	"backgroundClip",
+	"backgroundRepeat",
+	// Transform
+	"transform",
+	"transformOrigin",
+	// Image
+	"objectFit",
+	"objectPosition",
+	// Mask
+	"maskImage",
+	"maskPosition",
+	"maskSize",
+	"maskRepeat",
+	// Text stroke
+	"WebkitTextStroke",
+	"WebkitTextStrokeWidth",
+	"WebkitTextStrokeColor",
+	"WebkitBackgroundClip",
+	"WebkitTextFillColor",
+]);
+
+const OG_MODULES = new Set(["next/og", "@vercel/og"]);
+const IMAGE_CONVENTION = /\/(opengraph-image|twitter-image)(\.[^/]+)?\.[jt]sx$/;
+
+/** kebab-case is legal in a style object via string keys; normalize to camel. */
+const toCamelCase = (name) =>
+	name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+const satoriCss = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Restrict inline styles in satori-rendered JSX to what satori implements",
+		},
+		messages: {
+			unsupportedProperty:
+				"satori does not implement `{{property}}` — it is silently dropped from the rendered image (the PNG still comes out, just wrong, so no render test catches it). See https://github.com/vercel/satori#css for the supported subset.",
+			calc: "satori does not support `calc()` in `{{property}}` — the declaration is dropped. Compute the number in JS instead.",
+			missingFlex:
+				'This element has {{count}} children but no `display`. satori defaults every node to `display: flex`, and a node with more than one child must set it explicitly — add `display: "flex"` (or `"none"`) to make the intent survive.',
+			textWithElementSiblings:
+				"satori cannot lay out a text node next to element siblings — it throws at render. Wrap the text in its own element.",
+		},
+	},
+	create(context) {
+		const filename = context.physicalFilename || context.filename || "";
+		const isConventionFile = IMAGE_CONVENTION.test(filename.replace(/\\/g, "/"));
+		let importsOg = false;
+		/** Findings held until the whole file has been seen — the `next/og`
+		 * import is what proves the JSX is satori-bound, and a re-export or a
+		 * type-only file can carry JSX with no import at all. */
+		const findings = [];
+		const report = (descriptor) => findings.push(descriptor);
+
+		const checkStyleObject = (object) => {
+			for (const property of object.properties) {
+				if (property.type !== "Property") continue;
+				let name;
+				if (property.key.type === "Identifier" && !property.computed) {
+					name = property.key.name;
+				} else if (property.key.type === "Literal") {
+					name = String(property.key.value);
+				} else {
+					// A computed key is unknowable statically; a spread may carry
+					// anything. Silence beats guessing.
+					continue;
+				}
+				// CSS custom properties are supported (with var() and fallbacks).
+				if (name.startsWith("--")) continue;
+				const camel = toCamelCase(name);
+				if (!SUPPORTED.has(camel)) {
+					report({
+						node: property.key,
+						messageId: "unsupportedProperty",
+						data: { property: name },
+					});
+					continue;
+				}
+				if (
+					property.value.type === "Literal" &&
+					typeof property.value.value === "string" &&
+					property.value.value.includes("calc(")
+				) {
+					report({
+						node: property.value,
+						messageId: "calc",
+						data: { property: name },
+					});
+				}
+			}
+		};
+
+		// Both structural checks only count children that are *certainly*
+		// rendered. A `{cond ? <a/> : null}` child may collapse to nothing, and
+		// counting it would flag templates that lay out fine — a false positive in
+		// a rule the whole fleet inherits costs more than the miss.
+		const isCertainElement = (child) =>
+			child.type === "JSXElement" ||
+			child.type === "JSXFragment" ||
+			(child.type === "JSXExpressionContainer" &&
+				(child.expression.type === "JSXElement" ||
+					child.expression.type === "JSXFragment"));
+
+		/** Raw text, or an interpolation that can only be a string/number. */
+		const isCertainText = (child) => {
+			if (child.type === "JSXText") return child.value.trim() !== "";
+			if (child.type !== "JSXExpressionContainer") return false;
+			const expression = child.expression;
+			return (
+				(expression.type === "Literal" &&
+					typeof expression.value !== "boolean") ||
+				expression.type === "TemplateLiteral"
+			);
+		};
+
+		return {
+			ImportDeclaration(node) {
+				if (OG_MODULES.has(node.source.value)) importsOg = true;
+			},
+			JSXAttribute(node) {
+				if (node.name.type !== "JSXIdentifier" || node.name.name !== "style") {
+					return;
+				}
+				const value = node.value;
+				if (value?.type !== "JSXExpressionContainer") return;
+				if (value.expression.type !== "ObjectExpression") return;
+				checkStyleObject(value.expression);
+			},
+			JSXElement(node) {
+				const texts = node.children.filter(isCertainText);
+				const elements = node.children.filter(isCertainElement);
+				if (texts.length > 0 && elements.length > 0) {
+					report({ node, messageId: "textWithElementSiblings" });
+				}
+
+				const children = texts.length + elements.length;
+				if (children < 2) return;
+
+				// A component's own JSX is that component's business; only the
+				// intrinsic elements satori lays out carry the flex rule.
+				if (node.openingElement.name.type !== "JSXIdentifier") return;
+				if (!/^[a-z]/.test(node.openingElement.name.name)) return;
+
+				let styleObject;
+				let hasUnknownStyle = false;
+				for (const attribute of node.openingElement.attributes) {
+					if (attribute.type === "JSXSpreadAttribute") {
+						hasUnknownStyle = true;
+						continue;
+					}
+					if (attribute.name.name !== "style") continue;
+					if (attribute.value?.type !== "JSXExpressionContainer") {
+						hasUnknownStyle = true;
+					} else if (attribute.value.expression.type === "ObjectExpression") {
+						styleObject = attribute.value.expression;
+					} else {
+						hasUnknownStyle = true;
+					}
+				}
+				if (hasUnknownStyle) return;
+				const declaresDisplay = styleObject?.properties.some(
+					(property) =>
+						property.type === "Property" &&
+						!property.computed &&
+						(property.key.name === "display" ||
+							property.key.value === "display"),
+				);
+				if (declaresDisplay) return;
+				report({
+					node: node.openingElement,
+					messageId: "missingFlex",
+					data: { count: String(children) },
+				});
+			},
+			"Program:exit"() {
+				if (!importsOg && !isConventionFile) return;
+				for (const descriptor of findings) context.report(descriptor);
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "satori-css": satoriCss },
+};

package/lib/passthrough.js

@@ -1,8 +1,10 @@
 import { checkAgentGuideImport } from "./agent-guide.js";
+import { cleanGeneratedArtifacts, onlyGeneratedTypeErrors } from "./artifacts.js";
 import { toolDrift } from "./drift.js";
 import { FORMATTER } from "./formatter.js";
 import { hasKnipConfig, runKnip } from "./knip.js";
-import { run } from "./run.js";
+import { checkSeal } from "./migrations.js";
+import { run, runCapture, writeThrough } from "./run.js";
 
 /** `nk lint [...]` — oxlint, with extra args passed through (e.g. `--fix`). */
 export function lint(extraArgs = []) {
@@ -32,8 +34,19 @@ export function check() {
 			"  → add `@./node_modules/@ingram-tech/nk-dev/guide.md` to your CLAUDE.md (or run `nk init`).",
 		);
 	}
+	// Applied migrations are immutable. A no-op on sites without a `drizzle/`
+	// journal, so it costs non-database sites nothing.
+	const seal = checkSeal();
+	if (!seal.ok) {
+		console.error(`nk check: ${seal.reason}`);
+		console.error(
+			"  → restore the file and add a new migration, or run `nk migrations` to seal a newly generated one.",
+		);
+	}
 	warnToolDrift();
-	process.exit(lintFailed || fmtFailed || knipFailed || !guide.ok ? 1 : 0);
+	process.exit(
+		lintFailed || fmtFailed || knipFailed || !guide.ok || !seal.ok ? 1 : 0,
+	);
 }
 
 /** Non-fatal: surface superseded deps so drift doesn't silently re-accumulate. */
@@ -48,13 +61,58 @@ function warnToolDrift() {
 	);
 }
 
-/** `nk type-check` — the house type-check: regenerate Next's types, then tsc. */
+/**
+ * `nk type-check` — the house type-check: regenerate Next's types, then tsc.
+ *
+ * Recovers from damaged generated types. `tsconfig.json` feeds Next's
+ * typed-routes output back into `tsc`, and a killed dev server can leave it
+ * truncated mid-write; `next typegen` does not repair it, so the same syntax
+ * error inside `.next/` survives every re-run and reads as a source defect.
+ * When *every* reported error sits in generated output, the artifacts are
+ * cleaned and the check retried once — see {@link cleanGeneratedArtifacts}.
+ *
+ * The retry matters beyond the confusing message: a syntax error in generated
+ * output suppresses semantic diagnostics for the whole program, so real `src/`
+ * errors are hidden behind it. Recovering surfaces them and still exits
+ * non-zero — it never turns a failing check into a passing one.
+ */
 export function typeCheck() {
 	const typegen = run("next", ["typegen"]);
 	if (typegen !== 0) process.exit(typegen);
+
+	const first = runCapture("tsc", ["--noEmit"]);
+	if (first.status === 0 || !onlyGeneratedTypeErrors(first.output)) {
+		// Either a pass, or errors the caller needs to read and fix themselves.
+		writeThrough(first);
+		process.exit(first.status);
+	}
+
+	const removed = cleanGeneratedArtifacts();
+	console.error(
+		`nk type-check: every error was inside generated types — removed ${removed.join(", ")} and retrying.`,
+	);
+
+	const regen = run("next", ["typegen"]);
+	if (regen !== 0) process.exit(regen);
+	// Retry with inherited stdio: this is the run whose output matters, and it
+	// keeps colour when a human is watching.
 	process.exit(run("tsc", ["--noEmit"]));
 }
 
+/**
+ * `nk clean` — remove build artifacts that tools regenerate from source
+ * (Next's generated types, TypeScript incremental caches). Safe by
+ * construction: whatever owns an artifact rebuilds it on the next run.
+ */
+export function clean() {
+	const removed = cleanGeneratedArtifacts();
+	if (removed.length === 0) {
+		console.log("nk clean: no generated artifacts found.");
+		return;
+	}
+	console.log(`nk clean: removed ${removed.join(", ")}.`);
+}
+
 /** `nk test [...]` — vitest run, with extra args passed through. */
 export function test(extraArgs = []) {
 	process.exit(run("vitest", ["run", ...extraArgs]));

package/lib/run.js

@@ -21,6 +21,40 @@ export function run(tool, args = [], opts = {}) {
 	return res.status ?? (res.signal ? 1 : 0);
 }
 
+/**
+ * Like {@link run}, but captures the tool's output instead of inheriting stdio,
+ * so a caller can inspect it before deciding what to print. Returns the exit
+ * code plus the combined output; the caller is responsible for forwarding it.
+ *
+ * Colour is left to the tool: with stdio piped there is no TTY, so tools that
+ * auto-detect print plain text — which is also what makes their output
+ * parseable.
+ */
+export function runCapture(tool, args = [], opts = {}) {
+	const res = spawnSync("bun", ["x", tool, ...args], {
+		encoding: "utf8",
+		...opts,
+	});
+	if (res.error) {
+		if (res.error.code === "ENOENT") {
+			fail("could not run `bun` — is bun installed and on PATH?");
+		}
+		throw res.error;
+	}
+	return {
+		status: res.status ?? (res.signal ? 1 : 0),
+		stdout: res.stdout ?? "",
+		stderr: res.stderr ?? "",
+		output: `${res.stdout ?? ""}${res.stderr ?? ""}`,
+	};
+}
+
+/** Forward a {@link runCapture} result to this process's stdio, unchanged. */
+export function writeThrough({ stdout, stderr }) {
+	if (stdout) process.stdout.write(stdout);
+	if (stderr) process.stderr.write(stderr);
+}
+
 /** Print an `nk:`-prefixed error and exit non-zero. */
 export function fail(message) {
 	console.error(`nk: ${message}`);

package/oxlintrc.json

@@ -13,6 +13,8 @@
 		"nextkit/t-requires-values": "error",
 		"nextkit/t-no-positional-args": "error",
 		"nextkit/no-crypto-random-uuid": "warn",
+		"nextkit/no-redundant-node-crypto": "warn",
+		"nextkit/satori-css": "warn",
 		"no-unused-vars": "warn",
 		"typescript/no-non-null-assertion": "error",
 		"typescript/no-explicit-any": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
 	"license": "MIT",
 	"type": "module",
@@ -45,17 +45,18 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ast-grep/cli": "^0.44.1",
-		"@testing-library/jest-dom": "^6.9.1",
+		"@ast-grep/cli": "^0.45.0",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^7.0.0",
 		"@typescript/native": "npm:typescript@^7.0.2",
-		"jsdom": "^29.1.1",
-		"knip": "^6.27.0",
-		"oxfmt": "^0.59.0",
-		"oxlint": "^1.74.0",
+		"jsdom": "^30.0.1",
+		"knip": "^6.31.0",
+		"oxfmt": "^0.61.0",
+		"oxlint": "^1.76.0",
 		"typescript": "npm:@typescript/typescript6@^6.0.2",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=20"
+		"node": "^22.22.2 || ^24.15.0 || >=26.0.0"
 	}
 }