@ingram-tech/nk-dev 0.1.0 → 0.2.3

package/README.md

@@ -3,15 +3,16 @@
 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` / `check` / `type-check` / `build`);
+- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `check` / `type-check` / `build`);
 - 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`);
 - the **AI agent guide** (`guide.md`) imported into a site's `CLAUDE.md`;
 - **`nk init`**, which scaffolds a site to use all of the above.
 
 It's a single `devDependency` and pulls the toolchain (oxlint, oxfmt, tsc,
-vitest, jsdom, jest-dom) as hard dependencies — so one install gives you the
-whole stack instead of re-listing each tool per site.
+vitest, jsdom, jest-dom, knip) as hard dependencies — so one install gives you
+the whole stack instead of re-listing each tool per site.
 
 > **Runtime vs dev-time.** nk-dev is the *dev-time* bundle. Runtime features
 > (`@ingram-tech/email`, `nk-db`, `nk-auth`, …) stay separate packages that
@@ -33,10 +34,14 @@ bun install   # the prepare script wires the git hook
 | `.oxlintrc.json` | `extends` the shared oxlint rules (relative path — oxlint doesn't resolve package specifiers) |
 | `.oxfmtrc.json` | a copy of the house format config (oxfmt has no `extends`) |
 | `tsconfig.json` | `extends` `@ingram-tech/nk-dev/tsconfig/nextjs.json` + the site's own `include`/`paths` |
-| `vitest.config.ts` | `mergeConfig(nextkitTestConfig, {})` |
+| `knip.json` | seed config (knip has no shareable config): gates on dependency/file hygiene, with unused exports/types off (noisy); ignores `@ingram-tech/nk-dev` |
 | `.githooks/pre-commit` + `prepare` script | oxfmt format-on-commit |
 | `CLAUDE.md` | the agent-guide `@import` |
 
+It also prints a `vitest.config.ts` snippet (`mergeConfig(nextkitTestConfig, {})`
+from `@ingram-tech/nk-dev/vitest`) rather than writing the file — add it only if
+you test with Vitest (many sites use `bun:test`).
+
 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).
@@ -85,8 +90,10 @@ tsc), so versions stay under each site's control — nk just orchestrates.
 - **`nk format` / `nk format --check`** — formats code (JS/TS/JSON/CSS) with
   oxfmt and SQL with Prettier. `--check` verifies without writing (CI).
 - **`nk lint`** — `oxlint`.
-- **`nk check`** — `oxlint` + `oxfmt --check` plus SQL format verification, plus
-  the agent-guide import gate. The CI gate.
+- **`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 type-check`** — `next typegen && tsc --noEmit`.
 - **`nk build [...]`** — `next build`, extra args passed through.
 

package/bin/nk.js

@@ -2,6 +2,7 @@
 import { dev } from "../lib/dev.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";
 
 const USAGE = `nk — the nextkit CLI
@@ -17,8 +18,9 @@ Commands:
   format [--check]    Format code with oxfmt and SQL with Prettier. --check
                       verifies without writing (for CI).
   lint                Lint with oxlint.
-  check               Lint + format verification, plus the agent-guide import
-                      gate (the CI gate).
+  knip                Find unused dependencies / exports / files with knip.
+  check               The CI gate: lint + format verify + SQL + knip (when
+                      configured) + the agent-guide import gate.
   type-check          next typegen && tsc --noEmit.
   build [...]         next build (extra args passed through).
 
@@ -39,6 +41,9 @@ switch (cmd) {
 	case "lint":
 		lint();
 		break;
+	case "knip":
+		knip(rest);
+		break;
 	case "check":
 		await check();
 		break;

package/guide.md

@@ -10,7 +10,10 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
   (server: `verifyHuman` → silently drop bots; client: honeypot + signed token).
   Never ship a form without it.
 - **Send email only via `@ingram-tech/email`** — never add another mail client.
-- Format/lint with **oxlint + oxfmt** via `nk` (`@ingram-tech/nk-cli`); don't
+- **Never trust an external request body's shape — validate it with Zod, never
+  `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`.
@@ -48,6 +51,24 @@ if your frontend fetches it as an API, it's **`/api/…`**; if a provider, cron,
 queue calls it, it's **`/internal/…`**. Never put OAuth callbacks or webhooks in
 the UI/page tree, and never expose internal plumbing under `/api/`.
 
+## Data & migrations
+
+- **IDs are UUIDv7** — never UUIDv4 / `gen_random_uuid()` / `defaultRandom()` /
+  nanoids. UUIDv7 is time-ordered, so it keeps index locality instead of
+  fragmenting the B-tree on random inserts, and one uniform id format spans every
+  table. On Postgres ≥18 the column default is native `uuidv7()`
+  (`uuid("id").primaryKey().default(sql\`uuidv7()\`)`); set Better Auth
+  `advanced.database.generateId: false` so the DB — not Better Auth's JS nanoid —
+  mints ids. Ids that cross a **public contract** are skinned to `prefix_base58`
+  via `@ingram-tech/nk-db/id` (`createIdRegistry`) — never expose a raw UUID.
+  External ids you don't mint (Stripe `cus_`, OAuth) stay `text`.
+- **Migrations don't auto-apply on deploy.** Code ships ahead of the prod schema
+  unless someone runs the migration against the target DB — a page that reads a
+  newly-added column 500s in prod until then. Apply migrations with
+  `@ingram-tech/nk-db`'s drift-aware runner (`@ingram-tech/nk-db/migrate`), which
+  surfaces the real Postgres error and pre-flights journal drift. Generate **and
+  apply** in the same step; don't leave "run the migration" as a handoff.
+
 ## What nextkit provides (reach for these)
 
 - `@ingram-tech/email` — Cloudflare email: `sendEmail`, `fromAddress`
@@ -55,6 +76,6 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
 - `@ingram-tech/nk-db` — Postgres data layer: `createPool` (one TLS-aware pool) + `createQueries` (raw SQL) + `createDb` (Drizzle), plus a PGlite dev/test harness at `@ingram-tech/nk-db/pglite`
 - `@ingram-tech/bot-protection` — invisible form protection (honeypot + timing + Vercel BotID)
 - `@ingram-tech/newsletter` — Supabase newsletter: subscribe / send, 1-click unsubscribe
-- `@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` / `check` / `type-check` / `build`), the shared oxlint + oxfmt / TypeScript / Vitest config, the oxfmt format-on-commit hook, and this guide. `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` / `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.
 
 For detail on any package, read its README in `node_modules/@ingram-tech/<pkg>/`.

package/lib/init.js

@@ -48,13 +48,30 @@ const TSCONFIG = {
 	exclude: ["node_modules"],
 };
 
-const VITEST_CONFIG = `import { mergeConfig } from "vitest/config";
-import { nextkitTestConfig } from "@ingram-tech/nk-dev/vitest";
-
-// The shared nextkit preset (jsdom, globals, jest-dom matchers, Next.js mocks).
-// Add project-specific overrides as a second mergeConfig argument.
-export default mergeConfig(nextkitTestConfig, {});
-`;
+const VITEST_HINT = `import { mergeConfig } from "vitest/config";\\nimport { nextkitTestConfig } from "@ingram-tech/nk-dev/vitest";\\nexport default mergeConfig(nextkitTestConfig, {});`;
+
+// knip has no shareable config, so each site carries its own seed. The house
+// policy: gate on dependency/file hygiene (unused files/deps, unlisted,
+// unresolved) — its low-false-positive checks — and turn OFF unused
+// exports/types, which are noisy and usually intentional API surface. Run an
+// export-cleanup pass by flipping those back on when you want it.
+//
+// ignoreDependencies keeps @ingram-tech/nk-dev: knip doesn't follow the
+// relative-path `extends` in .oxlintrc/tsconfig, so a site that doesn't call the
+// `nk` bin gives knip no way to see nk-dev as used. Add `entry`/`ignore` as the
+// project grows (e.g. `scripts/**`, a self-contained `pulumi/**`).
+const KNIP = {
+	$schema: "https://unpkg.com/knip@6/schema.json",
+	ignoreDependencies: ["@ingram-tech/nk-dev"],
+	rules: {
+		exports: "off",
+		types: "off",
+		nsExports: "off",
+		nsTypes: "off",
+		enumMembers: "off",
+		duplicates: "off",
+	},
+};
 
 const PRE_COMMIT = `#!/bin/sh
 # nextkit pre-commit: format staged files with oxfmt, then re-stage them.
@@ -85,18 +102,20 @@ export function init() {
 	// 3. TypeScript config.
 	writeIfAbsent(resolve(cwd, "tsconfig.json"), (f) => writeJson(f, TSCONFIG));
 
-	// 4. Vitest config (the shared jsdom preset).
-	writeIfAbsent(resolve(cwd, "vitest.config.ts"), (f) =>
-		writeFileSync(f, VITEST_CONFIG),
-	);
+	// 4. Vitest config — only hint, never auto-write. Many sites test with
+	//    `bun:test` rather than Vitest, and an unused vitest.config.ts is noise.
+	hintVitestConfig(cwd);
 
-	// 5. Format-on-commit hook + git wiring.
+	// 5. knip config (unused deps/exports/files; run by `nk check`).
+	writeIfAbsent(resolve(cwd, "knip.json"), (f) => writeJson(f, KNIP));
+
+	// 6. Format-on-commit hook + git wiring.
 	setupGitHook(cwd);
 
-	// 6. Make sure the agent guide is imported into CLAUDE.md.
+	// 7. Make sure the agent guide is imported into CLAUDE.md.
 	ensureGuideImport(cwd);
 
-	// 7. A `prepare` script so the hook re-wires itself on every `bun install`.
+	// 8. A `prepare` script so the hook re-wires itself on every `bun install`.
 	ensurePrepareScript(cwd);
 
 	log("done. Next: `bun install`, then `nk check`.");
@@ -137,6 +156,15 @@ function ensureGuideImport(cwd) {
 	log("added the agent-guide import to CLAUDE.md");
 }
 
+function hintVitestConfig(cwd) {
+	if (existsSync(resolve(cwd, "vitest.config.ts"))) {
+		skip("vitest.config.ts");
+		return;
+	}
+	log("no vitest.config.ts — if you test with Vitest, create one:");
+	console.log(`      ${VITEST_HINT.replace(/\\n/g, "\n      ")}`);
+}
+
 function ensurePrepareScript(cwd) {
 	const pkgPath = resolve(cwd, "package.json");
 	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));

package/lib/knip.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { run } from "./run.js";
+
+// Knip has no shareable/extends config, so each repo carries its own. We treat
+// the *presence* of a knip config as opt-in: `nk check` only runs knip when one
+// of these exists, so sites that haven't adopted knip aren't suddenly gated.
+const CONFIG_FILES = [
+	"knip.json",
+	"knip.jsonc",
+	"knip.config.js",
+	"knip.config.ts",
+	"knip.ts",
+	"knip.js",
+];
+
+/** Whether the project has a knip config (a file, or a package.json#knip key). */
+export function hasKnipConfig(cwd = process.cwd()) {
+	if (CONFIG_FILES.some((f) => existsSync(resolve(cwd, f)))) return true;
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
+		return Boolean(pkg.knip);
+	} catch {
+		return false;
+	}
+}
+
+/** Run knip (dependency/export/file hygiene). Returns its exit code. */
+export function runKnip(extraArgs = []) {
+	return run("knip", extraArgs);
+}
+
+/** `nk knip` — run knip directly. */
+export function knip(extraArgs = []) {
+	process.exit(runKnip(extraArgs));
+}

package/lib/passthrough.js

@@ -1,6 +1,7 @@
 import { checkAgentGuideImport } from "./agent-guide.js";
 import { formatSql } from "./format.js";
 import { FORMATTER } from "./formatter.js";
+import { hasKnipConfig, runKnip } from "./knip.js";
 import { run } from "./run.js";
 
 /** `nk lint` — oxlint. */
@@ -8,7 +9,11 @@ export function lint() {
 	process.exit(run(FORMATTER.lint[0], FORMATTER.lint[1]));
 }
 
-/** `nk check` — the CI gate: lint + format verify (code) plus SQL format verify. */
+/**
+ * `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.
+ */
 export async 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.
@@ -16,6 +21,9 @@ export async function check() {
 	const fmtFailed = run(FORMATTER.checkFormat[0], FORMATTER.checkFormat[1]) !== 0;
 	await formatSql({ check: true });
 	const sqlFailed = Boolean(process.exitCode);
+	// 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;
 	// Keep the site on the shared-guidance channel: if it depends on
 	// @ingram-tech/nk-dev, its CLAUDE.md must @import the guide.
 	const guide = checkAgentGuideImport();
@@ -25,7 +33,9 @@ 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 || !guide.ok ? 1 : 0);
+	process.exit(
+		lintFailed || fmtFailed || sqlFailed || knipFailed || !guide.ok ? 1 : 0,
+	);
 }
 
 /** `nk type-check` — the house type-check: regenerate Next's types, then tsc. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.1.0",
+	"version": "0.2.3",
 	"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,6 +45,7 @@
 	"dependencies": {
 		"@testing-library/jest-dom": "^6.9.1",
 		"jsdom": "^29.1.1",
+		"knip": "^6.17.1",
 		"oxfmt": "^0.55.0",
 		"oxlint": "^1.70.0",
 		"prettier": "^3.8.3",

package/tsconfig/base.json

@@ -4,8 +4,14 @@
 	"compilerOptions": {
 		"target": "ESNext",
 		"lib": ["esnext"],
-		"module": "esnext",
-		"moduleResolution": "bundler",
+		// NodeNext so published packages ("type": "module") emit real Node ESM and
+		// tsc ENFORCES explicit .js extensions on relative imports (TS2835).
+		// "bundler" silently tolerates extensionless imports and emits them
+		// verbatim — invalid under Node ESM / Turbopack, a recurring break source.
+		// App consumers override back to "bundler" in nextjs.json (Next resolves
+		// modules itself and must not require .js extensions in app source).
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
 		"allowJs": true,
 		"skipLibCheck": true,
 		"strict": true,

package/tsconfig/nextjs.json

@@ -4,6 +4,11 @@
 	"extends": "./base.json",
 	"compilerOptions": {
 		"lib": ["dom", "dom.iterable", "esnext"],
+		// Next apps let the bundler resolve modules — keep "bundler" here so app
+		// source needn't use .js import extensions. (base.json is "nodenext" for
+		// published packages; this override insulates apps from that.)
+		"module": "esnext",
+		"moduleResolution": "bundler",
 		"jsx": "preserve",
 		"noEmit": true,
 		"declaration": false,