@ingram-tech/nk-dev 0.1.0 → 0.2.0

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 ignoring `@ingram-tech/nk-dev` (knip has no shareable config) |
 | `.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

@@ -55,6 +55,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,17 @@ 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. This seed ignores
+// @ingram-tech/nk-dev: a site that runs raw tools (not the `nk` bin) gives knip
+// no way to see nk-dev as used, so without this it'd fail as an unused
+// dependency. (Sites that do call `nk` in scripts can drop it — knip will hint.)
+// Add `entry`/`ignore` as the project grows.
+const KNIP = {
+	$schema: "https://unpkg.com/knip@6/schema.json",
+	ignoreDependencies: ["@ingram-tech/nk-dev"],
+};
 
 const PRE_COMMIT = `#!/bin/sh
 # nextkit pre-commit: format staged files with oxfmt, then re-stage them.
@@ -85,18 +89,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. knip config (unused deps/exports/files; run by `nk check`).
+	writeIfAbsent(resolve(cwd, "knip.json"), (f) => writeJson(f, KNIP));
 
-	// 5. Format-on-commit hook + git wiring.
+	// 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 +143,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.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,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",