@ingram-tech/nk-dev 0.2.5 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 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` / `check` / `type-check` / `build`);
+- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `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`);
@@ -46,10 +46,6 @@ Everything is `extends`-based, so the house config is enforced by default but
 overridable — layer your own rules on top, or replace a stub entirely (e.g. drop
 in a `biome.json` instead of the oxlint/oxfmt stubs).
 
-Already on the old split packages or `@ingram-tech/biome-config`? Run the
-codemod — see
-[`oxlint-migration.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/oxlint-migration.md).
-
 ## The `nk` command
 
 Point your package.json scripts at it:
@@ -62,6 +58,7 @@ Point your package.json scripts at it:
 		"lint": "nk lint",
 		"check": "nk check",
 		"type-check": "nk type-check",
+		"test": "nk test",
 		"build": "nk build"
 	}
 }
@@ -81,6 +78,9 @@ tsc), so versions stay under each site's control — nk just orchestrates.
 
 - **`nk init`** — scaffold this project to use nextkit (see above). Idempotent:
   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.
 - **`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
@@ -88,13 +88,15 @@ tsc), so versions stay under each site's control — nk just orchestrates.
     `DATABASE_URL`, then `next dev --turbopack`. No Docker, no daemon.
   - **Plain** — otherwise just `next dev` (static/marketing sites with no DB).
 - **`nk format` / `nk format --check`** — formats code (JS/TS/JSON/CSS) with
-  oxfmt and SQL with Prettier. `--check` verifies without writing (CI).
+  oxfmt. `--check` verifies without writing (CI). SQL isn't formatted — it's
+  generated (drizzle migrations, `pg_dump` baselines, pglite fixtures).
 - **`nk lint`** — `oxlint`.
 - **`nk knip`** — `knip` (unused dependencies / exports / files).
-- **`nk check`** — `oxlint` + `oxfmt --check` + SQL format verification + `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.
+- **`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.
 - **`nk type-check`** — `next typegen && tsc --noEmit`.
+- **`nk test [...]`** — `vitest run`, extra args passed through.
 - **`nk build [...]`** — `next build`, extra args passed through.
 
 ## Exports
@@ -110,11 +112,11 @@ tsc), so versions stay under each site's control — nk just orchestrates.
 "@ingram-tech/nk-dev/guide.md"               // the AI agent guide
 ```
 
-## Why Prettier for SQL?
+## Why no SQL formatting?
 
-oxfmt is the formatter for code and stays that way — Prettier is never used for
-JS/TS. But oxfmt can't format SQL, so nk-dev bundles `prettier` +
-`prettier-plugin-sql` **as its own dependencies** and uses them only for `.sql`
-files. Prettier therefore never lands in any app's `package.json`. A site's own
-`.prettierrc` / package.json `"prettier"` settings are honored if present;
-otherwise nk defaults to tabs + the Postgres dialect.
+oxfmt is the formatter for code, and it can't format SQL — but nk-dev doesn't
+format SQL at all. The SQL in our repos is ~entirely generated (drizzle
+migrations, `pg_dump` baselines, pglite fixtures), so formatting it only churned
+generated files and crashed on psql directives (`\restrict`) for no gain. nk-dev
+therefore carries no `prettier` dependency; if a site has a leftover
+`.prettierignore`, `nk doctor --fix` removes it.

package/bin/nk.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { dev } from "../lib/dev.js";
+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, typeCheck } from "../lib/passthrough.js";
+import { build, check, lint, test, typeCheck } from "../lib/passthrough.js";
 
 const USAGE = `nk — the nextkit CLI
 
@@ -13,18 +14,21 @@ Commands:
   init                Scaffold this project to use nextkit: writes the oxlint /
                       oxfmt / TypeScript / Vitest config, the format-on-commit
                       hook, and the agent-guide import. Skips files that exist.
+  doctor [--fix]      Report drift from the canonical nk-dev toolchain (scripts,
+                      superseded deps, config extends, guide import); --fix applies.
   dev                 Start the Next dev server (Turbopack). Boots local PGlite
                       first when @ingram-tech/nk-db is installed (no Docker).
-  format [--check]    Format code with oxfmt and SQL with Prettier. --check
-                      verifies without writing (for CI).
+  format [--check]    Format code with oxfmt. --check verifies without writing.
   lint                Lint with oxlint.
   knip                Find unused dependencies / exports / files with knip.
-  check               The CI gate: lint + format verify + SQL + knip (when
-                      configured) + the agent-guide import gate.
+  check               The CI gate: lint + format verify + knip (when configured)
+                      + the agent-guide import gate.
   type-check          next typegen && tsc --noEmit.
+  test [...]          vitest run (extra args passed through).
   build [...]         next build (extra args passed through).
 
-Code formats with oxfmt and lints with oxlint; SQL formats with Prettier.`;
+Code formats with oxfmt and lints with oxlint. SQL is not formatted (it's
+generated); nk-dev carries no Prettier.`;
 
 const [cmd, ...rest] = process.argv.slice(2);
 
@@ -32,11 +36,14 @@ switch (cmd) {
 	case "init":
 		init();
 		break;
+	case "doctor":
+		doctor(rest);
+		break;
 	case "dev":
 		dev(rest);
 		break;
 	case "format":
-		await format({ check: rest.includes("--check") });
+		format({ check: rest.includes("--check") });
 		break;
 	case "lint":
 		lint();
@@ -45,11 +52,14 @@ switch (cmd) {
 		knip(rest);
 		break;
 	case "check":
-		await check();
+		check();
 		break;
 	case "type-check":
 		typeCheck();
 		break;
+	case "test":
+		test(rest);
+		break;
 	case "build":
 		build(rest);
 		break;

package/guide.md

@@ -14,9 +14,11 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
   `as`-cast it.** Every `/api` route and webhook handler takes untrusted input;
   an `as` cast is a lie the type-checker can't catch at runtime.
 - Format/lint with **oxlint + oxfmt** via `nk` (`@ingram-tech/nk-dev`); don't
-  reintroduce ESLint, nor Prettier for code (`nk` uses Prettier only for SQL,
-  which oxfmt can't format). `nk` is optional convenience that only orchestrates
-  the standard tools — the site must stay buildable with plain `next build` / `next dev`.
+  reintroduce ESLint or Prettier (SQL isn't formatted — it's generated). nk-dev
+  owns the toolchain: don't re-declare `oxfmt`/`oxlint`/`typescript` or the
+  retired `@ingram-tech/{oxlint,typescript}-config` — `nk doctor` flags the drift.
+  `nk` is optional convenience that only orchestrates the standard tools — the
+  site must stay buildable with plain `next build` / `next dev`.
 
 ## Route & URL conventions
 
@@ -81,6 +83,6 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
 - `@ingram-tech/nk-billing` — Stripe primitives: subscriptions, a Stripe-side wallet, and an optional Postgres credit ledger behind the `/credits` subpath. Prices resolve at runtime by Stripe `lookup_key` — **never hardcode a price id**, so test and live share one code path
 - `@ingram-tech/bot-protection` — invisible form protection (honeypot + timing + Vercel BotID)
 - `@ingram-tech/nk-i18n` — type-safe, English-as-key i18n: the English source text *is* the key (no `en.json`), ICU MessageFormat, colocated JSON catalogs; routing is left to the site
-- `@ingram-tech/nk-dev` — the whole dev toolchain in one devDependency: the `nk` command (`nk dev` boots local PGlite via `@ingram-tech/nk-db` if installed, then Next; plus `nk format` / `lint` / `knip` / `check` / `type-check` / `build`), the shared oxlint + oxfmt / TypeScript / Vitest config, knip, the oxfmt format-on-commit hook, and this guide. `nk check` runs every fast checker (oxlint, oxfmt, SQL, knip) in one gate. `nk init` scaffolds a site to use it all.
+- `@ingram-tech/nk-dev` — the whole dev toolchain in one devDependency: the `nk` command (`nk dev` boots local PGlite via `@ingram-tech/nk-db` if installed, then Next; plus `nk format` / `lint` / `knip` / `check` / `type-check` / `test` / `build`), the shared oxlint + oxfmt / TypeScript / Vitest config, knip, the oxfmt format-on-commit hook, and this guide. `nk check` runs every fast checker (oxlint, oxfmt, knip) in one gate; `nk doctor --fix` reconciles a site back to the canonical toolchain. `nk init` scaffolds a site to use it all.
 
 For detail on any package, read its README in `node_modules/@ingram-tech/<pkg>/`.

package/lib/doctor.js

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { SUPERSEDED_DEPS } from "./drift.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);
+// the value is what the script should run.
+const CANONICAL_SCRIPTS = {
+	lint: "nk lint",
+	format: "nk format",
+	check: "nk check",
+	"type-check": "nk type-check",
+};
+
+const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
+const OXLINTRC_EXTENDS = "./node_modules/@ingram-tech/nk-dev/oxlintrc.json";
+const TSCONFIG_EXTENDS = "@ingram-tech/nk-dev/tsconfig/nextjs.json";
+
+/** Read + parse a JSON file, or null if absent/unparseable. */
+function readJson(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+/** Write JSON in the house style (tabs, trailing newline). */
+function writeJson(file, value) {
+	writeFileSync(file, `${JSON.stringify(value, null, "\t")}\n`);
+}
+
+/**
+ * Collect drift findings for the repo at `cwd`. Each finding is
+ * `{ id, level, message, fix }`, where `fix(cwd)` applies the correction and
+ * returns a short past-tense note. `level` is "error" (breaks the model) or
+ * "warn" (cosmetic / cleanup).
+ */
+function findings(cwd) {
+	const out = [];
+	const pkgPath = resolve(cwd, "package.json");
+	const pkg = readJson(pkgPath);
+	if (!pkg) return out; // not a package — nothing to reconcile
+
+	// 1. Scripts point at `nk`. Accept either `type-check` or `typecheck` key.
+	const scripts = pkg.scripts ?? {};
+	for (const [name, wanted] of Object.entries(CANONICAL_SCRIPTS)) {
+		const key =
+			name === "type-check" &&
+			scripts["typecheck"] !== undefined &&
+			scripts["type-check"] === undefined
+				? "typecheck"
+				: name;
+		const current = scripts[key];
+		if (current === wanted) continue;
+		// Only flag `check` as missing if the repo has scripts at all; a repo
+		// truly without a check script still wants one on the nk model.
+		out.push({
+			id: `script:${key}`,
+			level: "error",
+			message:
+				current === undefined
+					? `missing \`${key}\` script (want "${wanted}")`
+					: `\`${key}\` script is "${current}" (want "${wanted}")`,
+			fix: (dir) => {
+				const p = resolve(dir, "package.json");
+				const j = readJson(p);
+				j.scripts ??= {};
+				j.scripts[key] = wanted;
+				writeJson(p, j);
+				return `set \`${key}\` → "${wanted}"`;
+			},
+		});
+	}
+
+	// 2. Superseded deps still declared.
+	const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+	if (deps["@ingram-tech/nk-dev"]) {
+		const superseded = SUPERSEDED_DEPS.filter((d) => d in deps);
+		for (const dep of superseded) {
+			out.push({
+				id: `dep:${dep}`,
+				level: "error",
+				message: `depends on \`${dep}\` — superseded by @ingram-tech/nk-dev`,
+				fix: (dir) => {
+					const p = resolve(dir, "package.json");
+					const j = readJson(p);
+					delete j.dependencies?.[dep];
+					delete j.devDependencies?.[dep];
+					writeJson(p, j);
+					return `removed \`${dep}\``;
+				},
+			});
+		}
+	} else {
+		out.push({
+			id: "dep:nk-dev-missing",
+			level: "warn",
+			message:
+				"does not depend on @ingram-tech/nk-dev (run `nk init` to adopt the toolchain)",
+		});
+	}
+
+	// 3. .oxlintrc.json extends nk-dev (not the retired oxlint-config).
+	const oxPath = resolve(cwd, ".oxlintrc.json");
+	const ox = readJson(oxPath);
+	if (ox) {
+		const ext = [].concat(ox.extends ?? []);
+		if (!ext.includes(OXLINTRC_EXTENDS)) {
+			out.push({
+				id: "oxlintrc:extends",
+				level: "error",
+				message: `.oxlintrc.json does not extend nk-dev's config (extends: ${JSON.stringify(ox.extends ?? null)})`,
+				fix: (dir) => {
+					const p = resolve(dir, ".oxlintrc.json");
+					const j = readJson(p);
+					// Keep any non-superseded extends (e.g. a local tier-b tweak
+					// living outside oxlint-config), drop oxlint-config, ensure ours.
+					const kept = []
+						.concat(j.extends ?? [])
+						.filter(
+							(e) =>
+								!String(e).includes("oxlint-config") &&
+								e !== OXLINTRC_EXTENDS,
+						);
+					j.extends = [OXLINTRC_EXTENDS, ...kept];
+					j.$schema ??= "./node_modules/oxlint/configuration_schema.json";
+					writeJson(p, j);
+					return "repointed .oxlintrc.json extends → nk-dev";
+				},
+			});
+		}
+	}
+
+	// 4. tsconfig.json extends nk-dev's tsconfig (not the retired typescript-config).
+	const tsPath = resolve(cwd, "tsconfig.json");
+	const ts = readJson(tsPath);
+	if (ts && String(ts.extends ?? "").includes("typescript-config")) {
+		out.push({
+			id: "tsconfig:extends",
+			level: "error",
+			message: `tsconfig.json extends "${ts.extends}" — use nk-dev's tsconfig`,
+			fix: (dir) => {
+				const p = resolve(dir, "tsconfig.json");
+				const j = readJson(p);
+				j.extends = TSCONFIG_EXTENDS;
+				writeJson(p, j);
+				return `repointed tsconfig.json extends → ${TSCONFIG_EXTENDS}`;
+			},
+		});
+	}
+
+	// 5. CLAUDE.md imports the shared guide.
+	const claudePath = resolve(cwd, "CLAUDE.md");
+	if (deps["@ingram-tech/nk-dev"]) {
+		const claude = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
+		if (claude === null || !/@\S*nk-dev\/guide\.md/.test(claude)) {
+			out.push({
+				id: "claude:guide-import",
+				level: "error",
+				message:
+					claude === null
+						? "no CLAUDE.md importing the nk-dev guide"
+						: "CLAUDE.md does not @import the nk-dev guide",
+				fix: (dir) => {
+					const p = resolve(dir, "CLAUDE.md");
+					const body = existsSync(p)
+						? readFileSync(p, "utf8")
+						: "# Project\n";
+					writeFileSync(
+						p,
+						`${body.replace(/\n*$/, "")}\n\n${GUIDE_IMPORT}\n`,
+					);
+					return "added the guide import to CLAUDE.md";
+				},
+			});
+		}
+	}
+
+	// 6. knip.json ignoreDependencies referencing superseded packages (stale).
+	const knipPath = resolve(cwd, "knip.json");
+	const knip = readJson(knipPath);
+	if (knip && Array.isArray(knip.ignoreDependencies)) {
+		const stale = knip.ignoreDependencies.filter((d) =>
+			SUPERSEDED_DEPS.includes(d),
+		);
+		if (stale.length) {
+			out.push({
+				id: "knip:stale-ignores",
+				level: "warn",
+				message: `knip.json ignoreDependencies references removed packages: ${stale.join(", ")}`,
+				fix: (dir) => {
+					const p = resolve(dir, "knip.json");
+					const j = readJson(p);
+					j.ignoreDependencies = j.ignoreDependencies.filter(
+						(d) => !SUPERSEDED_DEPS.includes(d),
+					);
+					writeJson(p, j);
+					return `pruned stale knip ignoreDependencies: ${stale.join(", ")}`;
+				},
+			});
+		}
+	}
+
+	// 7. .prettierignore is now dead weight (nk no longer formats SQL).
+	const prettierIgnore = resolve(cwd, ".prettierignore");
+	if (existsSync(prettierIgnore)) {
+		out.push({
+			id: "prettierignore",
+			level: "warn",
+			message:
+				".prettierignore is unused (nk no longer runs Prettier) — remove it",
+			fix: (dir) => {
+				rmSync(resolve(dir, ".prettierignore"));
+				return "removed .prettierignore";
+			},
+		});
+	}
+
+	return out;
+}
+
+/**
+ * `nk doctor [--fix]` — report drift from the canonical nk-dev model (scripts,
+ * dependencies, oxlint/tsconfig extends, the CLAUDE.md guide import, stale knip
+ * ignores, a dead .prettierignore). With `--fix`, apply every auto-fixable
+ * finding, then remind to reinstall.
+ */
+export function doctor(args = []) {
+	const fix = args.includes("--fix");
+	const cwd = process.cwd();
+	const results = findings(cwd);
+
+	if (results.length === 0) {
+		console.log("nk doctor: ✓ on the canonical nk-dev toolchain — no drift.");
+		process.exit(0);
+	}
+
+	if (!fix) {
+		const errors = results.filter((r) => r.level === "error").length;
+		console.log(`nk doctor: ${results.length} finding(s):\n`);
+		for (const r of results) {
+			const mark = r.level === "error" ? "✗" : "•";
+			console.log(`  ${mark} ${r.message}`);
+		}
+		console.log(
+			`\n  Run \`nk doctor --fix\` to apply the ${results.filter((r) => r.fix).length} auto-fixable one(s).`,
+		);
+		// Exit non-zero only when there are model-breaking findings, so `nk
+		// doctor` can gate CI while cosmetic warnings don't.
+		process.exit(errors > 0 ? 1 : 0);
+	}
+
+	let applied = 0;
+	let touchedDeps = false;
+	for (const r of results) {
+		if (!r.fix) {
+			console.log(`  – ${r.message} (manual)`);
+			continue;
+		}
+		const note = r.fix(cwd);
+		console.log(`  ✓ ${note}`);
+		applied++;
+		if (r.id.startsWith("dep:")) touchedDeps = true;
+	}
+	console.log(`\nnk doctor: applied ${applied} fix(es).`);
+	if (touchedDeps) console.log("  → run `bun install` to sync the lockfile.");
+	process.exit(0);
+}

package/lib/drift.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Packages whose job `@ingram-tech/nk-dev` now owns — either because it bundles
+ * the tool (oxfmt, oxlint) or because it superseded a standalone shared-config /
+ * CLI / hooks package. A site on the nk-dev toolchain shouldn't re-declare any
+ * of these: doing so either splits a tool's version across two pins (the exact
+ * drift nk-dev centralizes away) or keeps a dead dependency on a retired package.
+ */
+export const SUPERSEDED_DEPS = [
+	"oxfmt",
+	"oxlint",
+	"prettier",
+	"prettier-plugin-sql",
+	"@ingram-tech/oxlint-config",
+	"@ingram-tech/typescript-config",
+	"@ingram-tech/nk-cli",
+	"@ingram-tech/git-hooks",
+];
+
+/**
+ * The superseded packages this repo still declares. Empty when the repo is
+ * clean, or when it doesn't depend on nk-dev at all (nothing to enforce).
+ */
+export function toolDrift(cwd = process.cwd()) {
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
+	} catch {
+		return [];
+	}
+	const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+	if (!deps["@ingram-tech/nk-dev"]) return [];
+	return SUPERSEDED_DEPS.filter((d) => d in deps);
+}

package/lib/format.js

@@ -1,123 +1,17 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { join, relative } from "node:path";
 import { FORMATTER } from "./formatter.js";
 import { run } from "./run.js";
 
-const require = createRequire(import.meta.url);
-
-// House SQL defaults, used only when the site has no Prettier config of its own
-// (matches the house tabs/4/88 style + the PostgreSQL dialect; without the
-// explicit widths Prettier falls back to 80/2).
-const SQL_DEFAULTS = {
-	useTabs: true,
-	tabWidth: 4,
-	printWidth: 88,
-	language: "postgresql",
-};
-
 /**
  * `nk format` / `nk format --check`.
  *
- * Code (JS/TS/JSON/CSS) goes through oxfmt; SQL goes through Prettier, which
- * oxfmt can't format. Prettier + prettier-plugin-sql are bundled with nk-dev,
- * so they never appear in any app's dependencies — the "no Prettier for code"
- * rule still holds, it's just the one file type oxfmt lacks.
+ * Code (JS/TS/JSON/CSS) goes through oxfmt — the one formatter nk owns. SQL is
+ * intentionally NOT formatted: it's almost entirely generated (drizzle
+ * migrations, `pg_dump` baselines, pglite fixtures), so a SQL formatter only
+ * churns generated files and chokes on psql directives (`\restrict`, …) for no
+ * real gain. Hand-written SQL is rare and fine unformatted. This is why nk-dev
+ * carries no `prettier` dependency.
  */
-export async function format({ check }) {
+export function format({ check }) {
 	const op = check ? FORMATTER.checkFormat : FORMATTER.write;
-	const code = run(op[0], op[1]);
-	if (code !== 0) process.exitCode = code;
-
-	if (await formatSql({ check })) process.exitCode = 1;
-}
-
-/**
- * Format (or, with `check`, verify) every tracked `.sql` file via Prettier.
- * Returns true when a check found unformatted files — the caller owns the exit
- * code (inferring failure from the `process.exitCode` global misattributes any
- * earlier failure to SQL).
- */
-export async function formatSql({ check }) {
-	const files = sqlFiles();
-	if (files.length === 0) return false;
-
-	const prettier = require("prettier");
-	const pluginPath = require.resolve("prettier-plugin-sql");
-
-	let unformatted = 0;
-	let written = 0;
-	for (const file of files) {
-		// git ls-files lists tracked files deleted from the worktree without
-		// `git rm`; reading one would throw an unhandled ENOENT.
-		if (!existsSync(file)) continue;
-		const source = readFileSync(file, "utf8");
-		// The site's own .prettierrc / package.json "prettier" wins over our
-		// defaults; we always inject the bundled SQL plugin + parser.
-		const siteConfig = (await prettier.resolveConfig(file)) ?? {};
-		const options = {
-			...SQL_DEFAULTS,
-			...siteConfig,
-			parser: "sql",
-			plugins: [
-				pluginPath,
-				...(siteConfig.plugins ?? []).filter(
-					(p) => !String(p).includes("prettier-plugin-sql"),
-				),
-			],
-		};
-
-		if (check) {
-			if (!(await prettier.check(source, options))) {
-				unformatted++;
-				console.error(`  ${relative(process.cwd(), file)}`);
-			}
-		} else {
-			const out = await prettier.format(source, options);
-			if (out !== source) {
-				writeFileSync(file, out);
-				written++;
-			}
-		}
-	}
-
-	if (check && unformatted > 0) {
-		console.error(
-			`nk: ${unformatted} SQL file(s) need formatting — run \`nk format\`.`,
-		);
-		return true;
-	}
-	if (!check && written > 0) {
-		console.log(`nk: formatted ${written} SQL file(s).`);
-	}
-	return false;
-}
-
-/** Tracked + untracked-not-ignored `.sql` files; falls back to an fs walk. */
-function sqlFiles() {
-	// -z: NUL-separated, unquoted — the default output octal-escapes non-ASCII
-	// filenames, which then match no real path.
-	const res = spawnSync(
-		"git",
-		["ls-files", "-z", "--cached", "--others", "--exclude-standard", "*.sql"],
-		{ encoding: "utf8" },
-	);
-	if (res.status === 0) {
-		return res.stdout.split("\0").filter(Boolean);
-	}
-	return walkSql(process.cwd());
-}
-
-const SKIP_DIRS = new Set(["node_modules", ".next", ".git", "dist", "build"]);
-
-function walkSql(dir, out = []) {
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		if (entry.isDirectory()) {
-			if (!SKIP_DIRS.has(entry.name)) walkSql(join(dir, entry.name), out);
-		} else if (entry.name.endsWith(".sql")) {
-			out.push(join(dir, entry.name));
-		}
-	}
-	return out;
+	process.exit(run(op[0], op[1]));
 }

package/lib/oxlint-plugins/base-ui.js

@@ -0,0 +1,121 @@
+// nextkit oxlint JS plugin: catch Radix-era props left on Base UI
+// (@base-ui/react) shadcn wrappers that silently do nothing post-migration.
+//
+// The trap: a Radix prop whose name is also a valid native DOM attribute is
+// accepted by Base UI's wrapper prop types (they extend the rendered element's
+// DOM props) and then dropped at runtime. `onSelect` on a menu item is the
+// canonical case: it type-checks as the DOM text-selection handler on the
+// rendered <div>, so tsc stays silent, and it never fires on click. The menu
+// action just does nothing. Base UI's Menu.Item activates via `onClick`.
+//
+// tsc CANNOT catch this class (the prop is a legitimate DOM attribute), which
+// is exactly why it needs a lint rule. Note the mirror image: non-DOM Radix
+// renames (asChild -> render, forceMount -> keepMounted, onValueCommit ->
+// onValueCommitted, delayDuration -> delay, Accordion type -> openMultiple) are
+// NOT listed here because they are not valid DOM attributes, so tsc already
+// errors on them. Only add an entry when the old prop is a valid DOM attribute
+// on the element the wrapper renders (i.e. genuinely silent). Otherwise you add
+// noise that duplicates the type-checker.
+//
+// Matching is by the shadcn wrapper's JSX element name, which is stable across
+// nextkit sites. Aliased imports (rare) are not matched; that is an accepted
+// limitation, not a correctness hole (the type-checker still guards renames).
+//
+// The same component names exist in Radix-based shadcn, where `onSelect` is the
+// CORRECT API. So the rule only activates for projects that actually depend on
+// @base-ui/react; on Radix (or UI-less) sites it is inert. This lets the shared
+// nextkit ruleset enable it as an error fleet-wide without false positives.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const baseUiCache = new Map();
+
+const pkgDeclaresBaseUi = (pkgPath) => {
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+		return Boolean(
+			pkg.dependencies?.["@base-ui/react"] ||
+			pkg.devDependencies?.["@base-ui/react"] ||
+			pkg.peerDependencies?.["@base-ui/react"],
+		);
+	} catch {
+		return false;
+	}
+};
+
+// Walk up to the nearest package.json and report whether it declares
+// @base-ui/react, memoizing every directory visited so a lint run pays the fs
+// cost once per project subtree.
+const projectUsesBaseUi = (fromDir) => {
+	const seen = [];
+	let dir = fromDir;
+	let result = null;
+	while (result === null) {
+		if (baseUiCache.has(dir)) {
+			result = baseUiCache.get(dir);
+		} else {
+			seen.push(dir);
+			const pkgPath = join(dir, "package.json");
+			const parent = dirname(dir);
+			if (existsSync(pkgPath)) result = pkgDeclaresBaseUi(pkgPath);
+			else if (parent === dir) result = false;
+			else dir = parent;
+		}
+	}
+	for (const d of seen) baseUiCache.set(d, result);
+	return result;
+};
+
+// component name -> { bannedProp: replacementProp }
+const BANNED = {
+	// Base UI Menu.Item (and its checkbox/radio variants) activate via onClick.
+	DropdownMenuItem: { onSelect: "onClick" },
+	DropdownMenuCheckboxItem: { onSelect: "onClick" },
+	DropdownMenuRadioItem: { onSelect: "onClick" },
+	ContextMenuItem: { onSelect: "onClick" },
+	ContextMenuCheckboxItem: { onSelect: "onClick" },
+	ContextMenuRadioItem: { onSelect: "onClick" },
+	MenubarItem: { onSelect: "onClick" },
+	MenubarCheckboxItem: { onSelect: "onClick" },
+	MenubarRadioItem: { onSelect: "onClick" },
+};
+
+const elementNameOf = (attributeNode) => {
+	const opening = attributeNode.parent;
+	if (!opening || opening.type !== "JSXOpeningElement") return null;
+	const name = opening.name;
+	return name && name.type === "JSXIdentifier" ? name.name : null;
+};
+
+const noRadixPropsOnBaseUi = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Disallow Radix-era props that Base UI wrappers silently ignore",
+		},
+	},
+	create(context) {
+		const filename = context.physicalFilename || context.filename || "";
+		if (!filename || !projectUsesBaseUi(dirname(filename))) return {};
+		return {
+			JSXAttribute(node) {
+				if (!node.name || node.name.type !== "JSXIdentifier") return;
+				const banned = BANNED[elementNameOf(node)];
+				if (!banned) return;
+				const replacement = banned[node.name.name];
+				if (!replacement) return;
+				context.report({
+					node: node.name,
+					message: `\`${node.name.name}\` does nothing on this Base UI component and is silently dropped at runtime. Use \`${replacement}\` instead (a Radix -> Base UI leftover the type-checker cannot catch).`,
+				});
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-radix-props-on-base-ui": noRadixPropsOnBaseUi },
+};

package/lib/passthrough.js

@@ -1,5 +1,5 @@
 import { checkAgentGuideImport } from "./agent-guide.js";
-import { formatSql } from "./format.js";
+import { toolDrift } from "./drift.js";
 import { FORMATTER } from "./formatter.js";
 import { hasKnipConfig, runKnip } from "./knip.js";
 import { run } from "./run.js";
@@ -11,15 +11,15 @@ export function lint() {
 
 /**
  * `nk check` — the CI gate. Runs every fast checker and reports them all before
- * failing: oxlint, oxfmt (format), SQL format, knip (when configured), and the
- * agent-guide import gate.
+ * failing: oxlint, oxfmt (format), knip (when configured), and the agent-guide
+ * import gate. Tooling drift (superseded deps) is reported as a non-fatal
+ * warning — `nk doctor --fix` resolves it.
  */
-export async function check() {
+export function check() {
 	// Run every gate before deciding (no short-circuit), so one failure doesn't
 	// hide another. oxc splits lint (oxlint) and format (oxfmt), so we run both.
 	const lintFailed = run(FORMATTER.lint[0], FORMATTER.lint[1]) !== 0;
 	const fmtFailed = run(FORMATTER.checkFormat[0], FORMATTER.checkFormat[1]) !== 0;
-	const sqlFailed = await formatSql({ check: true });
 	// knip (unused deps/exports/files). Opt-in: only when the repo has a knip
 	// config — knip has no shareable config, so absence means "not adopted".
 	const knipFailed = hasKnipConfig() ? runKnip() !== 0 : false;
@@ -32,8 +32,19 @@ export async function check() {
 			"  → add `@./node_modules/@ingram-tech/nk-dev/guide.md` to your CLAUDE.md (or run `nk init`).",
 		);
 	}
-	process.exit(
-		lintFailed || fmtFailed || sqlFailed || knipFailed || !guide.ok ? 1 : 0,
+	warnToolDrift();
+	process.exit(lintFailed || fmtFailed || knipFailed || !guide.ok ? 1 : 0);
+}
+
+/** Non-fatal: surface superseded deps so drift doesn't silently re-accumulate. */
+function warnToolDrift() {
+	const drift = toolDrift();
+	if (drift.length === 0) return;
+	console.error(
+		`nk check: ${drift.length} dependency(ies) superseded by @ingram-tech/nk-dev — ${drift.join(", ")}`,
+	);
+	console.error(
+		"  → nk-dev already provides these; run `nk doctor --fix` to remove them.",
 	);
 }
 
@@ -44,6 +55,11 @@ export function typeCheck() {
 	process.exit(run("tsc", ["--noEmit"]));
 }
 
+/** `nk test [...]` — vitest run, with extra args passed through. */
+export function test(extraArgs = []) {
+	process.exit(run("vitest", ["run", ...extraArgs]));
+}
+
 /** `nk build [...]` — next build, with extra args passed through. */
 export function build(extraArgs = []) {
 	process.exit(run("next", ["build", ...extraArgs]));

package/oxlintrc.json

@@ -1,9 +1,11 @@
 {
 	"plugins": ["typescript", "unicorn", "oxc", "react", "jsx-a11y", "import"],
+	"jsPlugins": ["@ingram-tech/nk-dev/oxlint-plugin"],
 	"categories": {
 		"correctness": "error"
 	},
 	"rules": {
+		"nextkit/no-radix-props-on-base-ui": "error",
 		"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.2.5",
+	"version": "0.4.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",
@@ -30,6 +30,7 @@
 		"./oxlintrc.json": "./oxlintrc.json",
 		"./oxfmtrc.json": "./oxfmtrc.json",
 		"./tier-b.json": "./tier-b.json",
+		"./oxlint-plugin": "./lib/oxlint-plugins/base-ui.js",
 		"./tsconfig": "./tsconfig/nextjs.json",
 		"./tsconfig/base.json": "./tsconfig/base.json",
 		"./tsconfig/nextjs.json": "./tsconfig/nextjs.json",
@@ -45,13 +46,11 @@
 	"dependencies": {
 		"@testing-library/jest-dom": "^6.9.1",
 		"jsdom": "^29.1.1",
-		"knip": "^6.23.0",
-		"oxfmt": "^0.56.0",
-		"oxlint": "^1.71.0",
-		"prettier": "^3.9.3",
-		"prettier-plugin-sql": "^0.20.0",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.9"
+		"knip": "^6.25.0",
+		"oxfmt": "^0.58.0",
+		"oxlint": "^1.73.0",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
 	},
 	"engines": {
 		"node": ">=20"