@ingram-tech/nk-dev 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @ingram-tech/nk-dev
+
+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 shared **oxlint + oxfmt**, **TypeScript**, and **Vitest** config;
+- 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.
+
+> **Runtime vs dev-time.** nk-dev is the *dev-time* bundle. Runtime features
+> (`@ingram-tech/email`, `nk-db`, `nk-auth`, …) stay separate packages that
+> peer-depend on `next`/`react`. See the dev-toolchain carve-out in
+> [`philosophy.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/philosophy.md).
+
+## Install
+
+```sh
+bun add -d @ingram-tech/nk-dev
+bunx nk init
+bun install   # the prepare script wires the git hook
+```
+
+`nk init` writes the config files (and skips any that already exist):
+
+| File | What |
+| --- | --- |
+| `.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, {})` |
+| `.githooks/pre-commit` + `prepare` script | oxfmt format-on-commit |
+| `CLAUDE.md` | the agent-guide `@import` |
+
+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:
+
+```jsonc
+{
+	"scripts": {
+		"dev": "nk dev",
+		"format": "nk format",
+		"lint": "nk lint",
+		"check": "nk check",
+		"type-check": "nk type-check",
+		"build": "nk build"
+	}
+}
+```
+
+`nk` shells out to the site's own `bunx`-resolved tools (oxlint, oxfmt, Next,
+tsc), so versions stay under each site's control — nk just orchestrates.
+
+> **`nk` is optional.** It only orchestrates the standard commands; it never
+> wraps or intercepts the Next.js build. Every site must stay fully buildable and
+> runnable with plain `next build` / `next dev` if `nk` is removed — see the
+> [`nk` carve-out](https://github.com/ingram-technologies/nextkit/blob/main/docs/philosophy.md).
+> The orchestration tests in this package check that the formatter resolves to
+> standard oxlint/oxfmt invocations and nothing more.
+
+### Commands
+
+- **`nk init`** — scaffold this project to use nextkit (see above). Idempotent:
+  skips files that already exist.
+- **`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
+    to it: boot Postgres-in-WASM, apply the `drizzle/` migrations, set
+    `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).
+- **`nk lint`** — `oxlint`.
+- **`nk check`** — `oxlint` + `oxfmt --check` plus SQL format verification, plus
+  the agent-guide import gate. The CI gate.
+- **`nk type-check`** — `next typegen && tsc --noEmit`.
+- **`nk build [...]`** — `next build`, extra args passed through.
+
+## Exports
+
+```jsonc
+"@ingram-tech/nk-dev/oxlintrc.json"          // oxlint rules (extend via relative path)
+"@ingram-tech/nk-dev/oxfmtrc.json"           // oxfmt config (copy; no extends)
+"@ingram-tech/nk-dev/tier-b.json"            // stricter opt-in lint tier
+"@ingram-tech/nk-dev/tsconfig/base.json"     // base TS config
+"@ingram-tech/nk-dev/tsconfig/nextjs.json"   // Next.js TS config (also "/tsconfig")
+"@ingram-tech/nk-dev/vitest"                 // nextkitTestConfig preset
+"@ingram-tech/nk-dev/vitest/setup"           // Vitest setup (jest-dom + Next mocks)
+"@ingram-tech/nk-dev/guide.md"               // the AI agent guide
+```
+
+## Why Prettier for SQL?
+
+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.

package/bin/format-staged.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * nextkit pre-commit: format staged files with oxfmt, then re-stage them.
+ *
+ * Centralizes the logic that lived inline in each repo's `.githooks/pre-commit`.
+ * Sites get it by pointing their committed `.githooks/pre-commit` at this bin —
+ * so the behavior updates in one place when this package is bumped.
+ *
+ * Behavior:
+ *   - Only staged files are touched (never the whole tree).
+ *   - Only extensions oxfmt understands are passed to it.
+ *   - oxfmt auto-discovers the repo's `.oxfmtrc.json` for house style.
+ *   - Files are re-staged after formatting so the commit includes the result.
+ *   - Formatting only — no lint gate on commit (lint runs in CI).
+ */
+import { execFileSync } from "node:child_process";
+
+const FORMATTABLE = /\.(jsx?|mjs|cjs|tsx?|mts|cts|json|jsonc|css|graphql|gql)$/;
+
+const git = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
+
+const stagedFiles = git(["diff", "--cached", "--name-only", "--diff-filter=ACMRTUXB"])
+	.split("\n")
+	.filter(Boolean);
+
+if (stagedFiles.length === 0) process.exit(0);
+
+const toFormat = stagedFiles.filter((f) => FORMATTABLE.test(f));
+if (toFormat.length === 0) process.exit(0);
+
+try {
+	execFileSync(
+		"bunx",
+		["oxfmt", "--write", "--no-error-on-unmatched-pattern", "--", ...toFormat],
+		{ stdio: "inherit" },
+	);
+} catch (err) {
+	console.error("[nextkit] oxfmt failed:", err.message);
+	process.exit(1);
+}
+
+// Re-stage only the files that were already staged and still exist.
+const existing = toFormat.filter((f) => {
+	try {
+		execFileSync("test", ["-e", f]);
+		return true;
+	} catch {
+		return false;
+	}
+});
+if (existing.length > 0) git(["add", "--", ...existing]);

package/bin/nk.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { dev } from "../lib/dev.js";
+import { format } from "../lib/format.js";
+import { init } from "../lib/init.js";
+import { build, check, lint, typeCheck } from "../lib/passthrough.js";
+
+const USAGE = `nk — the nextkit CLI
+
+Usage: nk <command> [options]
+
+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.
+  dev                 Start the Next dev server. Boots local PGlite first when
+                      @ingram-tech/nk-db is installed (no Docker); else plain dev.
+  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).
+  type-check          next typegen && tsc --noEmit.
+  build [...]         next build (extra args passed through).
+
+Code formats with oxfmt and lints with oxlint; SQL formats with Prettier.`;
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+switch (cmd) {
+	case "init":
+		init();
+		break;
+	case "dev":
+		dev(rest);
+		break;
+	case "format":
+		await format({ check: rest.includes("--check") });
+		break;
+	case "lint":
+		lint();
+		break;
+	case "check":
+		await check();
+		break;
+	case "type-check":
+		typeCheck();
+		break;
+	case "build":
+		build(rest);
+		break;
+	case "help":
+	case "--help":
+	case "-h":
+	case undefined:
+		console.log(USAGE);
+		break;
+	default:
+		console.error(`nk: unknown command "${cmd}"\n`);
+		console.log(USAGE);
+		process.exit(1);
+}

package/guide.md

@@ -0,0 +1,60 @@
+# nextkit (for AI agents)
+
+This is a **nextkit** site — Ingram Technologies' shared Next.js foundation.
+Core idea: don't reinvent shared concerns — reach for the `@ingram-tech/*`
+package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
+
+## Hard rules
+
+- **Any form that emails or stores a submission MUST use `@ingram-tech/bot-protection`**
+  (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
+  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`.
+
+## Route & URL conventions
+
+Keep the URL namespace honest about **who calls each route**:
+
+- **`/auth/…` — sign-in, via `@ingram-tech/nk-auth`.** Better Auth mounts here
+  through `basePath: authBasePath` (handler at `app/auth/[...all]/route.ts`,
+  client `createAuthClient({ basePath: authBasePath })`) — **not** the framework
+  default `/api/auth`. So **login / social OAuth callbacks are
+  `<site>/auth/callback/<provider>`** (e.g. Google `…/auth/callback/google`) —
+  that's the redirect URI you register with the IdP. Don't confuse it with
+  *connector* OAuth (the app acting as a client to a provider), which lives at
+  `/internal/connect/<provider>/callback` below.
+- **`/api/…` — the app's public API only.** Routes that external clients or your
+  own frontend consume *as an API*. Nothing else belongs here.
+- **`/internal/…` — all plumbing the public never calls as your API.** This is
+  where provider integrations, webhooks, workers and crons live:
+  - **`/internal/connect/<provider>/{start,callback}`** — the outbound OAuth /
+    app-install handshake. `start` (session-gated) kicks off the redirect to the
+    provider; **`callback` is the URL you register with the provider** — it
+    finishes the exchange/records the install and redirects the user back into the
+    app. e.g. `/internal/connect/slack/callback`, `/internal/connect/github/callback`.
+  - **`/internal/webhooks/<provider>`** — inbound provider webhooks (Slack,
+    GitHub, Stripe, …). Authenticated by the provider's signature/secret, not a
+    session. App-level (one URL per provider); route to the tenant from the
+    payload (team id, installation id, …).
+  - **`/internal/worker/<name>` · `/internal/cron/<name>`** — queue drains and
+    scheduled jobs, gated by a shared worker secret (Vercel Cron / queue calls them).
+
+Rule of thumb: if a human navigates to it, it's a **page** (normal route tree);
+if your frontend fetches it as an API, it's **`/api/…`**; if a provider, cron, or
+queue calls it, it's **`/internal/…`**. Never put OAuth callbacks or webhooks in
+the UI/page tree, and never expose internal plumbing under `/api/`.
+
+## What nextkit provides (reach for these)
+
+- `@ingram-tech/email` — Cloudflare email: `sendEmail`, `fromAddress`
+- `@ingram-tech/nk-auth` — Better Auth foundation: presets you spread into your own `betterAuth()` (mounts at `/auth` via `authBasePath`; org / JWT / passkey / pool / client helpers)
+- `@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.
+
+For detail on any package, read its README in `node_modules/@ingram-tech/<pkg>/`.

package/lib/agent-guide.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// A Claude Code `@import` of the shared guide, e.g.
+//   @./node_modules/@ingram-tech/nk-dev/guide.md
+//   @./web/node_modules/@ingram-tech/nk-dev/guide.md  (app in a subdir)
+const IMPORT_RE = /@\S*nk-dev\/guide\.md/;
+
+function readDeps(cwd) {
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
+		return { ...pkg.dependencies, ...pkg.devDependencies };
+	} catch {
+		return null; // no/unreadable package.json — nothing to enforce
+	}
+}
+
+// CLAUDE.md sits next to package.json for a standard site; for an app nested in a
+// subdir (e.g. `web/`) it lives one level up at the repo root. Check both.
+function findClaudeMd(cwd) {
+	for (const dir of [cwd, dirname(resolve(cwd))]) {
+		const p = resolve(dir, "CLAUDE.md");
+		if (existsSync(p)) return p;
+	}
+	return null;
+}
+
+/**
+ * nextkit's shared agent guidance (`@ingram-tech/nk-dev/guide.md`) only reaches
+ * an AI agent if the site's CLAUDE.md `@import`s it. A site can depend on nk-dev
+ * yet forget the import line — then the guidance silently never loads. When the
+ * package is a dependency, assert CLAUDE.md actually imports it.
+ *
+ * Returns `{ ok, reason }`. `ok` is true when there's nothing to enforce (the
+ * package isn't a dependency) or the import is present; `reason` explains a miss.
+ */
+export function checkAgentGuideImport(cwd = process.cwd()) {
+	const deps = readDeps(cwd);
+	if (!deps || !deps["@ingram-tech/nk-dev"]) return { ok: true };
+
+	const claudePath = findClaudeMd(cwd);
+	if (!claudePath) {
+		return {
+			ok: false,
+			reason: "depends on @ingram-tech/nk-dev but has no CLAUDE.md importing its guide",
+		};
+	}
+	if (!IMPORT_RE.test(readFileSync(claudePath, "utf8"))) {
+		return {
+			ok: false,
+			reason: "CLAUDE.md does not @import @ingram-tech/nk-dev/guide.md (shared agent guidance won't load)",
+		};
+	}
+	return { ok: true };
+}

package/lib/dev.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+/**
+ * Whether the site has `@ingram-tech/nk-db` installed — i.e. its `nk-pglite-dev`
+ * bin is available. Resolved from the site's own `node_modules`, so `nk` only
+ * orchestrates a tool the site already provides (the carve-out).
+ */
+function hasPgliteDev() {
+	try {
+		const require = createRequire(resolve(process.cwd(), "package.json"));
+		require.resolve("@ingram-tech/nk-db");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * `nk dev` — start the Next dev server on the golden-path local database.
+ *
+ * If `@ingram-tech/nk-db` is installed, hand off to its `nk-pglite-dev` bin: it
+ * boots PGlite (Postgres-in-WASM, no Docker), applies the `drizzle/` migrations,
+ * sets `DATABASE_URL`, and runs `next dev` itself. Otherwise just `next dev`
+ * (static/marketing sites with no database). PGlite logic lives in nk-db, not
+ * here — `nk` only orchestrates.
+ *
+ * `nk dev` does not boot local Supabase; the fleet has moved off it. The few
+ * Supabase-Postgres holdouts start it themselves until they migrate.
+ */
+export function dev(extraArgs = []) {
+	const command = hasPgliteDev()
+		? ["nk-pglite-dev", ...extraArgs]
+		: ["next", "dev", "--turbopack", ...extraArgs];
+	if (command[0] === "nk-pglite-dev") {
+		console.log("nk: @ingram-tech/nk-db found — booting local PGlite (no Docker)…");
+	}
+	// spawnSync inherits stdio and blocks until exit, so Ctrl-C reaches the child.
+	const res = spawnSync("bunx", command, { stdio: "inherit" });
+	process.exit(res.status ?? 0);
+}

package/lib/format.js

@@ -0,0 +1,108 @@
+import { spawnSync } from "node:child_process";
+import { 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 tab style + Supabase's Postgres dialect).
+const SQL_DEFAULTS = { useTabs: true, 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-cli,
+ * 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.
+ */
+export async function format({ check }) {
+	const op = check ? FORMATTER.checkFormat : FORMATTER.write;
+	const code = run(op[0], op[1]);
+	if (code !== 0) process.exitCode = code;
+
+	await formatSql({ check });
+}
+
+/** Format (or, with `check`, verify) every tracked `.sql` file via Prettier. */
+export async function formatSql({ check }) {
+	const files = sqlFiles();
+	if (files.length === 0) return;
+
+	const prettier = require("prettier");
+	const pluginPath = require.resolve("prettier-plugin-sql");
+
+	let unformatted = 0;
+	let written = 0;
+	for (const file of files) {
+		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\`.`,
+		);
+		process.exitCode = 1;
+	} else if (!check && written > 0) {
+		console.log(`nk: formatted ${written} SQL file(s).`);
+	}
+}
+
+/** Tracked + untracked-not-ignored `.sql` files; falls back to an fs walk. */
+function sqlFiles() {
+	const res = spawnSync(
+		"git",
+		["ls-files", "--cached", "--others", "--exclude-standard", "*.sql"],
+		{ encoding: "utf8" },
+	);
+	if (res.status === 0) {
+		return res.stdout
+			.split("\n")
+			.map((s) => s.trim())
+			.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;
+}

package/lib/formatter.js

@@ -0,0 +1,12 @@
+/**
+ * The code formatter/linter is oxc (oxlint + oxfmt). Each entry maps an
+ * operation nk needs to a `[tool, args]` invocation. Lint and format are kept
+ * as separate ops because oxc splits them across two tools; `nk check` runs
+ * both (see passthrough.js).
+ */
+export const FORMATTER = {
+	name: "oxc",
+	write: ["oxfmt", ["--write", "."]],
+	checkFormat: ["oxfmt", ["--check", "."]],
+	lint: ["oxlint", []],
+};

package/lib/init.js

@@ -0,0 +1,154 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Files live at the package root, two levels up from lib/.
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const log = (msg) => console.log(`nk init: ${msg}`);
+const skip = (file) => console.log(`nk init: ${file} already exists — left as-is.`);
+
+/** Write `value` as house-formatted JSON (tabs, trailing newline). */
+function writeJson(file, value) {
+	writeFileSync(file, `${JSON.stringify(value, null, "\t")}\n`);
+}
+
+/**
+ * Write `file` unless it already exists. Returns true if written.
+ * `build` produces the contents only when needed.
+ */
+function writeIfAbsent(file, build) {
+	if (existsSync(file)) {
+		skip(file);
+		return false;
+	}
+	build(file);
+	log(`wrote ${file}`);
+	return true;
+}
+
+// oxlint resolves `extends` as a path relative to the config file — NOT as a
+// package specifier — so it must point into node_modules.
+const OXLINTRC = {
+	$schema: "./node_modules/oxlint/configuration_schema.json",
+	extends: ["./node_modules/@ingram-tech/nk-dev/oxlintrc.json"],
+	ignorePatterns: ["dist", ".next"],
+};
+
+// TypeScript DOES resolve a package specifier in `extends`, so this stays a
+// clean one-liner. But inherited `include`/`exclude`/`paths` would resolve
+// relative to the *base* config (inside node_modules), so we declare our own.
+const TSCONFIG = {
+	extends: "@ingram-tech/nk-dev/tsconfig/nextjs.json",
+	compilerOptions: {
+		paths: { "@/*": ["./src/*"] },
+	},
+	include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+	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 PRE_COMMIT = `#!/bin/sh
+# nextkit pre-commit: format staged files with oxfmt, then re-stage them.
+# Logic lives in @ingram-tech/nk-dev, so a version bump updates it everywhere.
+set -eu
+exec bunx --bun nextkit-format-staged
+`;
+
+const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
+
+export function init() {
+	const cwd = process.cwd();
+
+	if (!existsSync(resolve(cwd, "package.json"))) {
+		console.error("nk init: no package.json here — run from your project root.");
+		process.exit(1);
+	}
+
+	// 1. oxlint config (extends the shared rules; add your own below).
+	writeIfAbsent(resolve(cwd, ".oxlintrc.json"), (f) => writeJson(f, OXLINTRC));
+
+	// 2. oxfmt config — oxfmt has no `extends`, so the house format config is
+	//    copied in. It's tiny and stable; editors auto-discover it too.
+	writeIfAbsent(resolve(cwd, ".oxfmtrc.json"), (f) =>
+		writeFileSync(f, readFileSync(resolve(PKG_ROOT, "oxfmtrc.json"), "utf8")),
+	);
+
+	// 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),
+	);
+
+	// 5. Format-on-commit hook + git wiring.
+	setupGitHook(cwd);
+
+	// 6. 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`.
+	ensurePrepareScript(cwd);
+
+	log("done. Next: `bun install`, then `nk check`.");
+}
+
+function setupGitHook(cwd) {
+	const hookDir = resolve(cwd, ".githooks");
+	const hook = resolve(hookDir, "pre-commit");
+	if (!existsSync(hook)) {
+		mkdirSync(hookDir, { recursive: true });
+		writeFileSync(hook, PRE_COMMIT);
+		log("wrote .githooks/pre-commit");
+	} else {
+		skip(".githooks/pre-commit");
+	}
+	chmodSync(hook, 0o755);
+	// Point git at the committed hooks dir now (the prepare script repeats this
+	// on future installs). Harmless if not a git repo.
+	spawnSync("git", ["config", "core.hooksPath", ".githooks"], {
+		cwd,
+		stdio: "ignore",
+	});
+}
+
+function ensureGuideImport(cwd) {
+	const claudePath = resolve(cwd, "CLAUDE.md");
+	if (!existsSync(claudePath)) {
+		writeFileSync(claudePath, `# Project\n\n${GUIDE_IMPORT}\n`);
+		log("wrote CLAUDE.md with the agent-guide import");
+		return;
+	}
+	const body = readFileSync(claudePath, "utf8");
+	if (body.includes("nk-dev/guide.md")) {
+		log("CLAUDE.md already imports the agent guide.");
+		return;
+	}
+	writeFileSync(claudePath, `${body.replace(/\n*$/, "")}\n\n${GUIDE_IMPORT}\n`);
+	log("added the agent-guide import to CLAUDE.md");
+}
+
+function ensurePrepareScript(cwd) {
+	const pkgPath = resolve(cwd, "package.json");
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+	pkg.scripts ??= {};
+	const wanted = "git config core.hooksPath .githooks || true";
+	if (pkg.scripts.prepare?.includes("core.hooksPath")) {
+		log("package.json already has a hooks `prepare` script.");
+		return;
+	}
+	pkg.scripts.prepare = pkg.scripts.prepare
+		? `${pkg.scripts.prepare} && ${wanted}`
+		: wanted;
+	writeJson(pkgPath, pkg);
+	log("added a `prepare` script to package.json (wires core.hooksPath).");
+}

package/lib/passthrough.js

@@ -0,0 +1,41 @@
+import { checkAgentGuideImport } from "./agent-guide.js";
+import { formatSql } from "./format.js";
+import { FORMATTER } from "./formatter.js";
+import { run } from "./run.js";
+
+/** `nk lint` — oxlint. */
+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. */
+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.
+	const lintFailed = run(FORMATTER.lint[0], FORMATTER.lint[1]) !== 0;
+	const fmtFailed = run(FORMATTER.checkFormat[0], FORMATTER.checkFormat[1]) !== 0;
+	await formatSql({ check: true });
+	const sqlFailed = Boolean(process.exitCode);
+	// 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();
+	if (!guide.ok) {
+		console.error(`nk check: ${guide.reason}`);
+		console.error(
+			"  → 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);
+}
+
+/** `nk type-check` — the house type-check: regenerate Next's types, then tsc. */
+export function typeCheck() {
+	const typegen = run("next", ["typegen"]);
+	if (typegen !== 0) process.exit(typegen);
+	process.exit(run("tsc", ["--noEmit"]));
+}
+
+/** `nk build [...]` — next build, with extra args passed through. */
+export function build(extraArgs = []) {
+	process.exit(run("next", ["build", ...extraArgs]));
+}

package/lib/run.js

@@ -0,0 +1,44 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Run a site-local tool through `bunx` (resolves node_modules/.bin first) with
+ * inherited stdio. Returns the exit code; never throws on a non-zero exit.
+ */
+export function run(tool, args = [], opts = {}) {
+	const res = spawnSync("bunx", [tool, ...args], { stdio: "inherit", ...opts });
+	if (res.error) {
+		if (res.error.code === "ENOENT") {
+			fail("could not run `bunx` — is bun installed and on PATH?");
+		}
+		throw res.error;
+	}
+	return res.status ?? 0;
+}
+
+/**
+ * Run a tool capturing its stdout (stderr still streams to the terminal).
+ * Exits the process if the tool fails — callers depend on the captured output.
+ */
+export function capture(tool, args = [], opts = {}) {
+	const res = spawnSync("bunx", [tool, ...args], {
+		encoding: "utf8",
+		stdio: ["inherit", "pipe", "inherit"],
+		...opts,
+	});
+	if (res.error) {
+		if (res.error.code === "ENOENT") {
+			fail("could not run `bunx` — is bun installed and on PATH?");
+		}
+		throw res.error;
+	}
+	if (res.status !== 0) {
+		fail(`\`${tool} ${args.join(" ")}\` exited with ${res.status}`);
+	}
+	return res.stdout ?? "";
+}
+
+/** Print an `nk:`-prefixed error and exit non-zero. */
+export function fail(message) {
+	console.error(`nk: ${message}`);
+	process.exit(1);
+}

package/oxfmtrc.json

@@ -0,0 +1,27 @@
+{
+	"useTabs": true,
+	"tabWidth": 4,
+	"printWidth": 88,
+	"singleQuote": false,
+	"jsxSingleQuote": false,
+	"quoteProps": "as-needed",
+	"trailingComma": "all",
+	"semi": true,
+	"arrowParens": "always",
+	"bracketSameLine": false,
+	"bracketSpacing": true,
+	"sortPackageJson": false,
+	"sortImports": false,
+	"sortTailwindcss": false,
+	"ignorePatterns": [
+		"**/*.md",
+		"**/*.mdx",
+		"**/*.yaml",
+		"**/*.yml",
+		"**/*.toml",
+		"**/*.html",
+		"dist",
+		".next",
+		"build"
+	]
+}

package/oxlintrc.json

@@ -0,0 +1,24 @@
+{
+	"plugins": ["typescript", "unicorn", "oxc", "react", "jsx-a11y", "import"],
+	"categories": {
+		"correctness": "error"
+	},
+	"rules": {
+		"no-unused-vars": "warn",
+		"typescript/no-non-null-assertion": "error",
+		"typescript/no-explicit-any": "error",
+		"typescript/consistent-type-imports": "off",
+		"unicorn/prefer-node-protocol": "off",
+		"react/exhaustive-deps": "warn",
+		"react/no-array-index-key": "off",
+		"react/no-danger": "off",
+		"jsx-a11y/label-has-associated-control": "off",
+		"jsx-a11y/click-events-have-key-events": "off",
+		"jsx-a11y/no-static-element-interactions": "off",
+		"jsx-a11y/interactive-supports-focus": "off",
+		"jsx-a11y/control-has-associated-label": "off",
+		"jsx-a11y/prefer-tag-over-role": "off",
+		"jsx-a11y/no-autofocus": "off",
+		"jsx-a11y/role-has-required-aria-props": "off"
+	}
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@ingram-tech/nk-dev",
+	"version": "0.1.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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-dev"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"tsconfig",
+		"vitest",
+		"oxlintrc.json",
+		"oxfmtrc.json",
+		"tier-b.json",
+		"guide.md"
+	],
+	"bin": {
+		"nk": "bin/nk.js",
+		"nextkit-format-staged": "bin/format-staged.mjs"
+	},
+	"exports": {
+		"./oxlintrc.json": "./oxlintrc.json",
+		"./oxfmtrc.json": "./oxfmtrc.json",
+		"./tier-b.json": "./tier-b.json",
+		"./tsconfig": "./tsconfig/nextjs.json",
+		"./tsconfig/base.json": "./tsconfig/base.json",
+		"./tsconfig/nextjs.json": "./tsconfig/nextjs.json",
+		"./vitest": "./vitest/index.ts",
+		"./vitest/setup": "./vitest/setup.ts",
+		"./guide.md": "./guide.md"
+	},
+	"scripts": {
+		"build": "true",
+		"type-check": "true",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@testing-library/jest-dom": "^6.9.1",
+		"jsdom": "^29.1.1",
+		"oxfmt": "^0.55.0",
+		"oxlint": "^1.70.0",
+		"prettier": "^3.8.3",
+		"prettier-plugin-sql": "^0.20.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}

package/tier-b.json

@@ -0,0 +1,35 @@
+{
+	"$schema": "./node_modules/oxlint/configuration_schema.json",
+	"rules": {
+		"no-restricted-imports": [
+			"error",
+			{
+				"paths": [
+					{
+						"name": "@supabase/supabase-js",
+						"message": "Golden-path data access uses @ingram-tech/nk-db (direct pg + Drizzle), not supabase-js."
+					},
+					{
+						"name": "pg",
+						"importNames": ["Pool", "Client"],
+						"allowTypeImports": true,
+						"message": "Build the pool with createPool() from @ingram-tech/nk-db, not `new Pool`/`new Client`. (`import type { Pool }` is fine.)"
+					}
+				]
+			}
+		]
+	},
+	"overrides": [
+		{
+			"files": [
+				"**/scripts/**",
+				"**/*.test.ts",
+				"**/*.test.tsx",
+				"**/__tests__/**",
+				"**/test/**",
+				"**/tests/**"
+			],
+			"rules": { "no-restricted-imports": "off" }
+		}
+	]
+}

package/tsconfig/base.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "@ingram-tech/typescript-config (base)",
+	"compilerOptions": {
+		"target": "ESNext",
+		"lib": ["esnext"],
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"allowJs": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"forceConsistentCasingInFileNames": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"incremental": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	}
+}

package/tsconfig/nextjs.json

@@ -0,0 +1,18 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"display": "@ingram-tech/typescript-config (Next.js app)",
+	"extends": "./base.json",
+	"compilerOptions": {
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"jsx": "preserve",
+		"noEmit": true,
+		"declaration": false,
+		"declarationMap": false,
+		"plugins": [{ "name": "next" }],
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	},
+	"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+	"exclude": ["node_modules"]
+}

package/vitest/index.ts

@@ -0,0 +1,37 @@
+import type { ViteUserConfig } from "vitest/config";
+
+/**
+ * Default Vitest configuration for Ingram Technologies projects: jsdom
+ * environment, global test APIs, v8 coverage, and the shared setup file
+ * ({@link ./setup}) that wires up jest-dom matchers and common Next.js mocks.
+ *
+ * Compose it in your `vitest.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig, mergeConfig } from "vitest/config";
+ * import { nextkitTestConfig } from "@ingram-tech/nk-dev/vitest";
+ *
+ * export default mergeConfig(
+ *   nextkitTestConfig,
+ *   defineConfig({
+ *     // project-specific overrides (e.g. resolve.alias for "@")
+ *   }),
+ * );
+ * ```
+ *
+ * Server-only library packages that don't need a DOM should instead set
+ * `test.environment: "node"` and skip the setup file.
+ */
+export const nextkitTestConfig: ViteUserConfig = {
+	test: {
+		environment: "jsdom",
+		globals: true,
+		setupFiles: ["@ingram-tech/nk-dev/vitest/setup"],
+		include: ["src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+		coverage: {
+			provider: "v8",
+			reporter: ["text", "json", "html"],
+			exclude: ["node_modules/", "**/*.d.ts", "**/*.config.*", "**/*.type.ts"],
+		},
+	},
+};

package/vitest/setup.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared Vitest setup, loaded via `setupFiles`. Keep this lean — it runs before
+ * every test file in consuming projects.
+ *
+ * - Registers `@testing-library/jest-dom` matchers (toBeInTheDocument, etc.).
+ * - Mocks `next/navigation` so components using `useRouter`/`usePathname`/
+ *   `useSearchParams` render in isolation without a real router.
+ */
+import "@testing-library/jest-dom/vitest";
+import { vi } from "vitest";
+
+vi.mock("next/navigation", () => ({
+	useRouter: () => ({
+		push: vi.fn(),
+		replace: vi.fn(),
+		back: vi.fn(),
+		forward: vi.fn(),
+		refresh: vi.fn(),
+		prefetch: vi.fn(),
+	}),
+	usePathname: () => "/",
+	useSearchParams: () => new URLSearchParams(),
+	useParams: () => ({}),
+	redirect: vi.fn(),
+	notFound: vi.fn(),
+}));