@ingram-tech/nk-dev 0.4.1 → 0.6.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` / `test` / `build`, plus `nk doctor`);
+- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `ast-grep` / `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`);
@@ -23,7 +23,7 @@ the whole stack instead of re-listing each tool per site.
 
 ```sh
 bun add -d @ingram-tech/nk-dev
-bunx nk init
+bun x nk init
 bun install   # the prepare script wires the git hook
 ```
 
@@ -64,7 +64,7 @@ Point your package.json scripts at it:
 }
 ```
 
-`nk` shells out to the site's own `bunx`-resolved tools (oxlint, oxfmt, Next,
+`nk` shells out to the site's own `bun x`-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
@@ -92,6 +92,12 @@ tsc), so versions stay under each site's control — nk just orchestrates.
   generated (drizzle migrations, `pg_dump` baselines, pglite fixtures).
 - **`nk lint`** — `oxlint`.
 - **`nk knip`** — `knip` (unused dependencies / exports / files).
+- **`nk ast-grep [...]`** — structural search & rewrite of TS/TSX by AST pattern,
+  via the vendored [ast-grep](https://ast-grep.github.io) (args passed through to
+  it). For large mechanical refactors — import rewrites, API renames, call-shape
+  changes — instead of hand-editing or `sed`. The workflow (search → preview →
+  apply → `nk format` + `nk type-check`) and its syntactic-not-semantic limits
+  live in the codemod skill, `skills/ts-codemod.md`.
 - **`nk check`** — `oxlint` + `oxfmt --check` + `knip` (only when the repo has a
   knip config) + the agent-guide import gate. The CI gate; runs every checker and
   reports them all before failing.

package/bin/format-staged.mjs

@@ -56,8 +56,8 @@ if (toFormat.length === 0) process.exit(0);
 
 try {
 	execFileSync(
-		"bunx",
-		["oxfmt", "--write", "--no-error-on-unmatched-pattern", "--", ...toFormat],
+		"bun",
+		["x", "oxfmt", "--write", "--no-error-on-unmatched-pattern", "--", ...toFormat],
 		{ stdio: "inherit" },
 	);
 } catch (err) {

package/bin/nk.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { astGrep } from "../lib/ast-grep.js";
 import { dev } from "../lib/dev.js";
 import { doctor } from "../lib/doctor.js";
 import { format } from "../lib/format.js";
@@ -21,6 +22,9 @@ Commands:
   format [--check]    Format code with oxfmt. --check verifies without writing.
   lint                Lint with oxlint.
   knip                Find unused dependencies / exports / files with knip.
+  ast-grep [...]      Structural search & rewrite of TS/TSX by AST pattern
+                      (vendored ast-grep; args passed through). For large
+                      mechanical refactors — see the codemod skill.
   check               The CI gate: lint + format verify + knip (when configured)
                       + the agent-guide import gate.
   type-check          next typegen && tsc --noEmit.
@@ -51,6 +55,9 @@ switch (cmd) {
 	case "knip":
 		knip(rest);
 		break;
+	case "ast-grep":
+		astGrep(rest);
+		break;
 	case "check":
 		check();
 		break;

package/guide.md

@@ -6,9 +6,13 @@ 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.
+- **Public contact/signup forms MUST use `@ingram-tech/nk-forms`** —
+  `handleFormSubmission` server-side (rate-limit → bot gate → validate →
+  escaped-email deliver → uniform 200) and `useFormSubmit` + `HoneypotInput`
+  client-side. It layers over `@ingram-tech/bot-protection`, which stays the
+  primitive for guarding *non-form* endpoints (a checkout, an authed route) —
+  call `checkBot` / `verifyHuman` directly there. Never ship a public form
+  without the bot gate.
 - **Send email only via `@ingram-tech/nk-email`** — never add another mail client.
 - **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;
@@ -74,6 +78,18 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
   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.
 
+## Large-scale / structural edits
+
+For a **mechanical change repeated across many files** — rewrite an import,
+rename an API, add a prop, reshape a call — don't hand-edit file by file or reach
+for `sed`. Use **`nk ast-grep`** (`@ingram-tech/nk-dev`): AST-aware structural
+search & rewrite of TS/TSX via the vendored ast-grep. **Before starting such a
+refactor, read the skill at
+`node_modules/@ingram-tech/nk-dev/skills/ts-codemod.md`** — it covers the
+search → preview → apply → `nk format` + `nk type-check` workflow, pattern
+syntax, and the syntactic-not-semantic limits (when to step up to a type-aware
+tool instead). One-off single-file edits: just edit the file.
+
 ## What nextkit provides (reach for these)
 
 - `@ingram-tech/nk-email` — Cloudflare email: `sendEmail`, `fromAddress`
@@ -81,8 +97,12 @@ 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), the PGlite dev/test harness at `@ingram-tech/nk-db/pglite`, the prefixed-id codec at `@ingram-tech/nk-db/id`, and the drift-aware migration runner at `@ingram-tech/nk-db/migrate`
 - `@ingram-tech/nk-api` — the standard HTTP API seam (Hono + `@hono/zod-openapi`): one `{ error, details? }` envelope, `createApiApp` / `createRouter`, auth + multi-tenant resource-scope middleware, pagination helpers, and an emitted OpenAPI/Swagger doc. Reach for it instead of hand-rolling route handlers
 - `@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/bot-protection` — invisible form protection (honeypot + timing + Vercel BotID); the primitive nk-forms builds on, used directly only for non-form endpoints
+- `@ingram-tech/nk-forms` — the public contact/signup submission pipeline over bot-protection + nk-email: `handleFormSubmission` (rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, `mintFormToken`, and `useFormSubmit` / `HoneypotInput` (`/react`). Reach for it instead of wiring bot-protection by hand
 - `@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-marketing` — Postgres-backed marketing & lifecycle email: contacts + consent, newsletter broadcast audiences, and idempotent triggered campaigns, with RFC 8058 one-click unsubscribe
+- `@ingram-tech/nk-seo` — SEO toolkit: metadata factory, JSON-LD builders, sitemap/robots routes, hreflang + canonical links, and an OG image template
+- `@ingram-tech/nk-blog` — file-indexed blog engine: frontmatter contract, limited-MDX rendering with a component vocabulary, RSS, blog SEO, GitHub publishing
 - `@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/ast-grep.js

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fail } from "./run.js";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolve the ast-grep native binary that nk-dev pins (`@ast-grep/cli`).
+ *
+ * We can't just `bun x ast-grep`: ast-grep is a *transitive* dep here (under
+ * nk-dev), so its bin is never linked into the site's top-level node_modules/.bin
+ * — `bun x ast-grep` falls through to a global on PATH (or re-downloads). And the
+ * nested `.bin/ast-grep` that does exist points at `@ast-grep/cli`'s tiny JS
+ * launcher, not the native binary: the launcher's postinstall normally swaps
+ * itself for the binary, but Bun blocks postinstall for untrusted deps, so it
+ * stays JS and warns on every run. The launcher's own `resolveBinaryPath()`
+ * returns the exact platform binary regardless — the one entry point that's
+ * correct across both states and both OSes.
+ */
+function astGrepBinary() {
+	const { resolveBinaryPath } = require("@ast-grep/cli/postinstall.js");
+	const bin = resolveBinaryPath();
+	if (!bin) {
+		fail(
+			"located @ast-grep/cli but not its native binary — reinstall deps without `--no-optional`.",
+		);
+	}
+	return bin;
+}
+
+/**
+ * `nk ast-grep [...]` — run the ast-grep binary vendored by nk-dev (structural
+ * search & rewrite of TS/TSX by AST pattern). A thin passthrough: every arg goes
+ * to ast-grep, so its own `--help`, `run`, and `scan` subcommands work unchanged.
+ * See the codemod skill at `skills/ts-codemod.md` for the workflow.
+ */
+export function astGrep(extraArgs = []) {
+	let bin;
+	try {
+		bin = astGrepBinary();
+	} catch (err) {
+		fail(
+			`could not resolve @ingram-tech/nk-dev's ast-grep (${err.message}) — reinstall your deps.`,
+		);
+	}
+	const res = spawnSync(bin, extraArgs, { stdio: "inherit" });
+	if (res.error) {
+		if (res.error.code === "ENOENT") fail(`ast-grep binary missing at ${bin}`);
+		throw res.error;
+	}
+	// A signal-killed child has status null — treat it as failure, not a pass.
+	process.exit(res.status ?? (res.signal ? 1 : 0));
+}

package/lib/dev.js

@@ -39,7 +39,7 @@ export function dev(extraArgs = []) {
 		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" });
+	const res = spawnSync("bun", ["x", ...command], { stdio: "inherit" });
 	// Signal-killed (status null) is a failure, not a clean exit.
 	process.exit(res.status ?? (res.signal ? 1 : 0));
 }

package/lib/init.js

@@ -50,6 +50,25 @@ const TSCONFIG = {
 
 const VITEST_HINT = `import { mergeConfig } from "vitest/config";\\nimport { nextkitTestConfig } from "@ingram-tech/nk-dev/vitest";\\nexport default mergeConfig(nextkitTestConfig, {});`;
 
+// The build-year env is the house fix for "current-year copyright" (and any
+// once-per-deploy value): compute it once here in Node, and Next inlines the
+// literal into both bundles — so nothing reads the clock at render. See
+// docs/code-style.md ("Never read the clock ... at render in a Client
+// Component"). The line to add to an existing next.config's top-level object:
+const BUILD_YEAR_ENV =
+	"env: { NEXT_PUBLIC_BUILD_YEAR: String(new Date().getFullYear()) },";
+const NEXT_CONFIG = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+	// Inlined at build so once-per-deploy values (e.g. the copyright year) are a
+	// literal in both bundles — never read the clock at a Client Component's
+	// render. See docs/code-style.md.
+	${BUILD_YEAR_ENV}
+};
+
+export default nextConfig;
+`;
+
 // 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
@@ -77,7 +96,7 @@ 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
+exec bun x --bun nextkit-format-staged
 `;
 
 const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
@@ -102,20 +121,24 @@ export function init() {
 	// 3. TypeScript config.
 	writeIfAbsent(resolve(cwd, "tsconfig.json"), (f) => writeJson(f, TSCONFIG));
 
-	// 4. Vitest config — only hint, never auto-write. Many sites test with
+	// 4. next.config with the build-year env. Written only when absent; an
+	//    existing config is never edited — we hint instead (see the function).
+	ensureNextConfig(cwd);
+
+	// 5. 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`).
+	// 6. 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.
+	// 7. Format-on-commit hook + git wiring.
 	setupGitHook(cwd);
 
-	// 7. Make sure the agent guide is imported into CLAUDE.md.
+	// 8. Make sure the agent guide is imported into CLAUDE.md.
 	ensureGuideImport(cwd);
 
-	// 8. A `prepare` script so the hook re-wires itself on every `bun install`.
+	// 9. A `prepare` script so the hook re-wires itself on every `bun install`.
 	ensurePrepareScript(cwd);
 
 	log("done. Next: `bun install`, then `nk check`.");
@@ -165,6 +188,26 @@ function hintVitestConfig(cwd) {
 	console.log(`      ${VITEST_HINT.replace(/\\n/g, "\n      ")}`);
 }
 
+// next.config is a Next.js file init doesn't own the contents of, so we never
+// rewrite an existing one (that's the site's config). Write a minimal typed
+// config when none exists; otherwise hint the one env line to add.
+function ensureNextConfig(cwd) {
+	const existing = ["next.config.ts", "next.config.mjs", "next.config.js"]
+		.map((name) => resolve(cwd, name))
+		.find((p) => existsSync(p));
+	if (!existing) {
+		writeFileSync(resolve(cwd, "next.config.ts"), NEXT_CONFIG);
+		log("wrote next.config.ts (with the NEXT_PUBLIC_BUILD_YEAR build env)");
+		return;
+	}
+	if (readFileSync(existing, "utf8").includes("NEXT_PUBLIC_BUILD_YEAR")) {
+		log("next.config already sets NEXT_PUBLIC_BUILD_YEAR.");
+		return;
+	}
+	log("next.config exists — add the build-year env to its config object:");
+	console.log(`      ${BUILD_YEAR_ENV}`);
+}
+
 function ensurePrepareScript(cwd) {
 	const pkgPath = resolve(cwd, "package.json");
 	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));

package/lib/oxlint-plugins/deferred-current-target.js

@@ -0,0 +1,109 @@
+// nextkit oxlint JS plugin rule: catch `event.currentTarget` reads that
+// outlive the event handler.
+//
+// The trap: React nulls a synthetic event's `currentTarget` once the handler
+// returns — it is per-dispatch state, reassigned as the one event object
+// traverses the propagation path (mirroring the DOM spec, where currentTarget
+// is only defined during dispatch). Reading it inside a callback that runs
+// after the handler — a functional setState updater, setTimeout, a promise
+// chain, a debounced closure — crashes with "Cannot read properties of null".
+// The failure is intermittent: React evaluates a setState updater eagerly when
+// the queue is empty, so the first keystroke works and only the replayed or
+// queued case crashes.
+//
+// tsc CANNOT catch this class: @types/react declares `currentTarget` non-null
+// (true during dispatch), and the nulling is a temporal invariant the type
+// system cannot express. Worse, `currentTarget` is the better-typed accessor
+// (typed as the element the handler is attached to, unlike `target`), so
+// TS-first code is steered toward exactly the property that expires. React 16
+// warned at runtime on any post-handler event access (event pooling); React 17
+// removed pooling and the warning with it, leaving `currentTarget` as the one
+// silently expiring property. Hence a lint rule.
+//
+// Detection: report `x.currentTarget` where `x` is bound as a parameter by an
+// ENCLOSING function other than the innermost one — i.e. the read crosses a
+// closure boundary out of the handler. Locals declared in the current function
+// (including a captured `const target = event.currentTarget` in the handler
+// body, which is the fix) never report.
+//
+// Known false positive: a closure the handler invokes synchronously itself
+// (e.g. `items.map((it) => event.currentTarget...)`). That pattern is rare and
+// fragile anyway; prefer capturing first, or suppress with a justified
+// oxlint-disable comment.
+
+const collectParamBindings = (params, into) => {
+	for (const param of params) {
+		if (param.type === "Identifier") into.add(param.name);
+		else if (
+			param.type === "AssignmentPattern" &&
+			param.left.type === "Identifier"
+		) {
+			into.add(param.left.name);
+		} else if (
+			param.type === "RestElement" &&
+			param.argument.type === "Identifier"
+		) {
+			into.add(param.argument.name);
+		}
+	}
+};
+
+const noDeferredCurrentTarget = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Disallow reading `event.currentTarget` inside a callback nested in the event handler; React nulls `currentTarget` after dispatch.",
+		},
+		messages: {
+			deferred:
+				"`{{name}}.currentTarget` is read inside a callback nested in the event handler. React nulls `currentTarget` once the handler returns, so this can crash when the callback runs later (e.g. a replayed setState updater). Capture the value into a local in the handler body and use that instead.",
+		},
+	},
+	create(context) {
+		const scopes = [];
+		const enterFunction = (node) => {
+			const bindings = new Set();
+			collectParamBindings(node.params, bindings);
+			scopes.push(bindings);
+		};
+		const exitFunction = () => {
+			scopes.pop();
+		};
+		return {
+			FunctionDeclaration: enterFunction,
+			"FunctionDeclaration:exit": exitFunction,
+			FunctionExpression: enterFunction,
+			"FunctionExpression:exit": exitFunction,
+			ArrowFunctionExpression: enterFunction,
+			"ArrowFunctionExpression:exit": exitFunction,
+			VariableDeclarator(node) {
+				// Track locals so a variable declared in the current function
+				// (including a rebound `event`) never reports.
+				if (scopes.length > 0 && node.id.type === "Identifier") {
+					scopes[scopes.length - 1].add(node.id.name);
+				}
+			},
+			MemberExpression(node) {
+				if (node.computed) return;
+				if (
+					node.property.type !== "Identifier" ||
+					node.property.name !== "currentTarget"
+				) {
+					return;
+				}
+				if (node.object.type !== "Identifier") return;
+				if (scopes.length < 2) return;
+				const name = node.object.name;
+				if (scopes[scopes.length - 1].has(name)) return;
+				if (!scopes.slice(0, -1).some((frame) => frame.has(name))) return;
+				context.report({ node, messageId: "deferred", data: { name } });
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-deferred-current-target": noDeferredCurrentTarget },
+};

package/lib/oxlint-plugins/index.js

@@ -0,0 +1,20 @@
+// The `nextkit` oxlint JS plugin: one rule per file, merged here. This is the
+// module `@ingram-tech/nk-dev/oxlint-plugin` resolves to and the shared
+// oxlintrc.json loads via `jsPlugins`.
+
+import baseUi from "./base-ui.js";
+import deferredCurrentTarget from "./deferred-current-target.js";
+import lucideIconSuffix from "./lucide-icon-suffix.js";
+import noRedirectOnlyPage from "./no-redirect-only-page.js";
+import redundantUseStateType from "./redundant-usestate-type.js";
+
+export default {
+	meta: { name: "nextkit" },
+	rules: {
+		...baseUi.rules,
+		...deferredCurrentTarget.rules,
+		...lucideIconSuffix.rules,
+		...noRedirectOnlyPage.rules,
+		...redundantUseStateType.rules,
+	},
+};

package/lib/oxlint-plugins/lucide-icon-suffix.js

@@ -0,0 +1,97 @@
+// nextkit oxlint JS plugin rule: enforce the `Icon` suffix on lucide-react
+// icon imports.
+//
+// lucide-react now ships every icon under an `Icon`-suffixed name (`HomeIcon`,
+// `ArrowRightIcon`, ...) and has deprecated the bare aliases (`Home`,
+// `ArrowRight`). Standardizing on the suffixed names keeps imports off the
+// deprecated path and makes an icon obvious at the use site: `<TrashIcon />`
+// reads as an icon, `<Trash />` reads like a domain component.
+//
+// The rule only fires on imports from "lucide-react", so it is inert on sites
+// that do not use lucide — no package.json gate needed (unlike the base-ui
+// rule, which keys off a component name that also exists in Radix). The
+// package's non-icon named exports (`LucideProps`, `IconNode`, `icons`,
+// `dynamicIconImports`) are skipped so the autofix never renames them to
+// nonsense like `LucidePropsIcon`.
+//
+// Autofix renames the import specifier and, when the local name is not aliased,
+// every reference to it in the file.
+
+const NON_ICON_EXPORTS = new Set([
+	"LucideProps",
+	"IconNode",
+	"icons",
+	"dynamicIconImports",
+]);
+
+const lucideIconSuffix = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Enforce the Icon suffix on lucide-react imports",
+		},
+		fixable: "code",
+		messages: {
+			missingIconSuffix:
+				"Import `{{imported}}` from lucide-react must use the Icon suffix: `{{suggested}}`.",
+		},
+	},
+	create(context) {
+		const sourceCode = context.sourceCode;
+		return {
+			ImportDeclaration(node) {
+				if (node.source.value !== "lucide-react") return;
+				for (const specifier of node.specifiers) {
+					if (specifier.type !== "ImportSpecifier") continue;
+					if (specifier.imported.type !== "Identifier") continue;
+
+					const importedName = specifier.imported.name;
+					if (
+						importedName.endsWith("Icon") ||
+						NON_ICON_EXPORTS.has(importedName)
+					) {
+						continue;
+					}
+
+					const suggested = `${importedName}Icon`;
+					const notAliased = specifier.imported.name === specifier.local.name;
+					context.report({
+						node: specifier,
+						messageId: "missingIconSuffix",
+						data: { imported: importedName, suggested },
+						fix(fixer) {
+							const fixes = [
+								fixer.replaceText(specifier.imported, suggested),
+							];
+							if (notAliased) {
+								for (const variable of sourceCode.getDeclaredVariables(
+									node,
+								)) {
+									if (variable.name !== specifier.local.name) {
+										continue;
+									}
+									for (const ref of variable.references) {
+										if (ref.identifier !== specifier.local) {
+											fixes.push(
+												fixer.replaceText(
+													ref.identifier,
+													suggested,
+												),
+											);
+										}
+									}
+								}
+							}
+							return fixes;
+						},
+					});
+				}
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "lucide-icon-suffix": lucideIconSuffix },
+};

package/lib/oxlint-plugins/no-redirect-only-page.js

@@ -0,0 +1,196 @@
+// nextkit oxlint JS plugin rule: flag App Router `page.tsx` files whose only
+// job is to call `redirect(...)`.
+//
+// A page that renders nothing and immediately redirects still costs a route
+// match, a server component render, and a `redirect()` throw on every request.
+// The same hop belongs in `next.config`'s `redirects()` array, where it is
+// handled at the routing layer before any rendering — cheaper and cacheable.
+//
+// This is a heuristic suggestion, not a correctness rule: it fires only when the
+// page body is a bare `redirect(...)` (optionally with a leading variable or
+// return) AND the destination is a statically extractable string / simple
+// template, so the equivalent config entry can be shown. Anything with real
+// logic is left alone. Scope is limited to `**/page.tsx`.
+//
+// Ported from the upstream Ingram ESLint rule, de-noised: that version emitted
+// two diagnostics per hit (the finding and a separate example); this emits one
+// with the config snippet inlined.
+
+const noRedirectOnlyPage = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description:
+				"Prefer next.config redirects over pages that only call redirect()",
+		},
+		messages: {
+			useConfigRedirect:
+				'This page only performs a redirect. Prefer a next.config redirect: add `{ source: "{{source}}", destination: "{{destination}}", permanent: false }` to `redirects()` — it bounces at the routing layer instead of rendering a page to do it.',
+		},
+	},
+	create(context) {
+		const filename = context.physicalFilename || context.filename || "";
+		if (!filename.endsWith("/page.tsx")) return {};
+
+		let hasRedirectCall = false;
+		let redirectDestination = null;
+		let isSimpleRedirect = true;
+		let redirectNode = null;
+
+		// Turn the file path into the route it serves: strip to the segment
+		// after `src/app`, drop `(group)` folders, map `[param]` to `:param`.
+		const getSourcePath = () => {
+			const match = filename.match(/src\/app(.*)\/page\.tsx$/);
+			if (!match) return null;
+			let path = match[1].replace(/\/\([^)]+\)/g, "");
+			if (!path) return "/";
+			return path.replace(/\[([^\]]+)\]/g, ":$1");
+		};
+
+		// True when a function body is nothing but a `redirect(...)` call,
+		// optionally preceded by a variable declaration or an early return.
+		const isOnlyRedirect = (body) => {
+			if (!body) return false;
+
+			if (body.type === "BlockStatement") {
+				const statements = body.body.filter(
+					(stmt) => stmt.type !== "EmptyStatement",
+				);
+				if (statements.length === 0 || statements.length > 2) {
+					return false;
+				}
+				for (const stmt of statements) {
+					if (stmt.type === "ExpressionStatement") {
+						const expr = stmt.expression;
+						if (
+							expr.type === "CallExpression" &&
+							expr.callee.type === "Identifier" &&
+							expr.callee.name === "redirect"
+						) {
+							continue;
+						}
+						return false;
+					}
+					if (
+						stmt.type === "VariableDeclaration" ||
+						stmt.type === "ReturnStatement"
+					) {
+						continue;
+					}
+					return false;
+				}
+				return true;
+			}
+
+			// Arrow function with a direct `redirect(...)` expression body.
+			return (
+				body.type === "CallExpression" &&
+				body.callee.type === "Identifier" &&
+				body.callee.name === "redirect"
+			);
+		};
+
+		// Pull a static destination out of the first `redirect()` argument, or
+		// null when it is dynamic in a way we cannot render as a config entry.
+		const extractDestination = (node) => {
+			if (!node.arguments || node.arguments.length === 0) return null;
+			const firstArg = node.arguments[0];
+
+			if (firstArg.type === "Literal" && typeof firstArg.value === "string") {
+				return firstArg.value;
+			}
+
+			if (firstArg.type === "TemplateLiteral") {
+				let result = "";
+				for (let i = 0; i < firstArg.quasis.length; i++) {
+					result += firstArg.quasis[i].value.raw;
+					if (i < firstArg.expressions.length) {
+						const expr = firstArg.expressions[i];
+						if (expr.type === "Identifier") {
+							result += `:${expr.name}`;
+						} else if (
+							expr.type === "AwaitExpression" &&
+							expr.argument &&
+							expr.argument.type === "CallExpression"
+						) {
+							result += ":id";
+						} else {
+							return null;
+						}
+					}
+				}
+				return result;
+			}
+
+			return null;
+		};
+
+		// Any component whose body is more than a bare redirect disqualifies the
+		// page. Covers all page shapes — `const XxxPage = () => {}`,
+		// `export default function Page() {}`, `export default () => {}` — so a
+		// function-declaration page with real logic is not falsely flagged.
+		const disqualifyIfComplex = (fn) => {
+			if (
+				fn &&
+				(fn.type === "ArrowFunctionExpression" ||
+					fn.type === "FunctionExpression" ||
+					fn.type === "FunctionDeclaration") &&
+				!isOnlyRedirect(fn.body)
+			) {
+				isSimpleRedirect = false;
+			}
+		};
+
+		return {
+			VariableDeclarator(node) {
+				if (node.id.type === "Identifier" && node.id.name.endsWith("Page")) {
+					disqualifyIfComplex(node.init);
+				}
+			},
+
+			FunctionDeclaration(node) {
+				if (node.id && node.id.name.endsWith("Page")) {
+					disqualifyIfComplex(node);
+				}
+			},
+
+			ExportDefaultDeclaration(node) {
+				disqualifyIfComplex(node.declaration);
+			},
+
+			CallExpression(node) {
+				if (
+					node.callee.type === "Identifier" &&
+					node.callee.name === "redirect"
+				) {
+					hasRedirectCall = true;
+					redirectNode = node;
+					redirectDestination = extractDestination(node);
+				}
+			},
+
+			"Program:exit"() {
+				if (
+					!hasRedirectCall ||
+					!isSimpleRedirect ||
+					!redirectDestination ||
+					!redirectNode
+				) {
+					return;
+				}
+				const source = getSourcePath();
+				if (!source) return;
+				context.report({
+					node: redirectNode,
+					messageId: "useConfigRedirect",
+					data: { source, destination: redirectDestination },
+				});
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-redirect-only-page": noRedirectOnlyPage },
+};

package/lib/oxlint-plugins/redundant-usestate-type.js

@@ -0,0 +1,157 @@
+// nextkit oxlint JS plugin rule: strip redundant `useState<T>` type arguments
+// that TypeScript already infers from the initial value.
+//
+// `useState<boolean>(false)`, `useState<string>("")`, `useState<number>(0)`
+// each annotate exactly the type React infers from the literal — pure noise.
+// `useState<number | undefined>(undefined)` is the same story spelled with a
+// union: `useState<number>()` (no argument) yields the identical
+// `[number | undefined, ...]` tuple with the identical `undefined` initial
+// value, so the union + explicit `undefined` argument are redundant too.
+//
+// Deliberately NARROWER than the upstream Ingram ESLint rule this is ported
+// from, on the two cases where that rule changed behavior instead of removing
+// redundancy:
+//   - No `null` handling. `useState<string | null>(null)` -> `useState<string>()`
+//     is a runtime change (the initial value becomes `undefined`); an autofix
+//     must never do that. Whether to prefer `undefined` over `null` is a style
+//     call this rule does not make.
+//   - No array handling. `useState<string[]>([])` is NOT redundant: `useState([])`
+//     infers `never[]`, not `string[]`, so the annotation is load-bearing. The
+//     upstream rule stripped it and silently broadened the state to `never[]`.
+//
+// tsc does not flag redundant annotations, so this is a lint-only cleanup; every
+// reported case is autofixable and behavior-preserving.
+
+const noRedundantUseStateType = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description:
+				"Disallow redundant useState type arguments that are inferable from the initial value",
+		},
+		fixable: "code",
+		messages: {
+			redundantSimpleType:
+				"Redundant `useState` type argument: `{{type}}` is already inferred from the initial value.",
+			redundantUndefinedUnion:
+				"Redundant `| undefined` in `useState` type: use `useState<{{baseType}}>()` instead of `useState<{{baseType}} | undefined>(undefined)`.",
+		},
+	},
+	create(context) {
+		const sourceCode = context.sourceCode;
+
+		// Remove the whole `<...>` type-argument list, brackets included, by
+		// deleting the span between the callee token and the opening `(`.
+		const removeTypeArguments = (fixer, typeArguments) => {
+			const before = sourceCode.getTokenBefore(typeArguments);
+			const after = sourceCode.getTokenAfter(typeArguments);
+			return fixer.removeRange([before.range[1], after.range[0]]);
+		};
+
+		return {
+			CallExpression(node) {
+				if (
+					node.callee.type !== "Identifier" ||
+					node.callee.name !== "useState"
+				) {
+					return;
+				}
+
+				const typeArguments = node.typeArguments;
+				if (!typeArguments || typeArguments.params.length === 0) return;
+
+				const typeParam = typeArguments.params[0];
+				const argument = node.arguments[0];
+
+				// Case 1: a scalar keyword type whose literal initial value
+				// infers exactly that type. Arrays are excluded on purpose (see
+				// the header): `useState<string[]>([])` is not redundant.
+				if (argument) {
+					const typeText = sourceCode.getText(typeParam);
+					const redundant =
+						(typeText === "boolean" &&
+							argument.type === "Literal" &&
+							typeof argument.value === "boolean") ||
+						(typeText === "string" &&
+							argument.type === "Literal" &&
+							typeof argument.value === "string") ||
+						(typeText === "number" &&
+							argument.type === "Literal" &&
+							typeof argument.value === "number") ||
+						(typeText === "undefined" &&
+							argument.type === "Identifier" &&
+							argument.name === "undefined");
+
+					if (redundant) {
+						context.report({
+							node: typeArguments,
+							messageId: "redundantSimpleType",
+							data: { type: typeText },
+							fix: (fixer) => removeTypeArguments(fixer, typeArguments),
+						});
+						return;
+					}
+				}
+
+				// Case 2: `T | undefined` with an explicit `undefined` initial
+				// value collapses to `useState<T>()`.
+				if (
+					typeParam.type === "TSUnionType" &&
+					argument &&
+					argument.type === "Identifier" &&
+					argument.name === "undefined"
+				) {
+					const rest = typeParam.types.filter(
+						(t) => t.type !== "TSUndefinedKeyword",
+					);
+					const undefined_ = typeParam.types.filter(
+						(t) => t.type === "TSUndefinedKeyword",
+					);
+					if (rest.length === 1 && undefined_.length === 1) {
+						const baseText = sourceCode.getText(rest[0]);
+						context.report({
+							node,
+							messageId: "redundantUndefinedUnion",
+							data: { baseType: baseText },
+							fix(fixer) {
+								const fixes = [fixer.replaceText(typeParam, baseText)];
+								if (node.arguments.length === 1) {
+									const openParen =
+										sourceCode.getTokenAfter(typeArguments);
+									const closeParen =
+										sourceCode.getTokenAfter(argument);
+									fixes.push(
+										fixer.replaceTextRange(
+											[openParen.range[0], closeParen.range[1]],
+											"()",
+										),
+									);
+								}
+								return fixes;
+							},
+						});
+						return;
+					}
+				}
+
+				// Case 3: bare `useState<undefined>()` with no initial value.
+				if (
+					typeParam.type === "TSUndefinedKeyword" &&
+					node.arguments.length === 0
+				) {
+					context.report({
+						node: typeArguments,
+						messageId: "redundantSimpleType",
+						data: { type: "undefined" },
+						fix: (fixer) => removeTypeArguments(fixer, typeArguments),
+					});
+				}
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-redundant-usestate-type": noRedundantUseStateType },
+};

package/lib/run.js

@@ -1,14 +1,18 @@
 import { spawnSync } from "node:child_process";
 
 /**
- * Run a site-local tool through `bunx` (resolves node_modules/.bin first) with
+ * Run a site-local tool through `bun x` (resolves node_modules/.bin first) with
  * inherited stdio. Returns the exit code; never throws on a non-zero exit.
+ *
+ * We spawn `bun x` rather than the `bunx` shim: on some installs (notably
+ * Windows and Git's bundled sh) only `bun` lands on PATH, and `bunx` is an
+ * alias for `bun x`, so this form works in a strict superset of environments.
  */
 export function run(tool, args = [], opts = {}) {
-	const res = spawnSync("bunx", [tool, ...args], { stdio: "inherit", ...opts });
+	const res = spawnSync("bun", ["x", tool, ...args], { stdio: "inherit", ...opts });
 	if (res.error) {
 		if (res.error.code === "ENOENT") {
-			fail("could not run `bunx` — is bun installed and on PATH?");
+			fail("could not run `bun` — is bun installed and on PATH?");
 		}
 		throw res.error;
 	}

package/oxlintrc.json

@@ -6,6 +6,10 @@
 	},
 	"rules": {
 		"nextkit/no-radix-props-on-base-ui": "error",
+		"nextkit/no-deferred-current-target": "error",
+		"nextkit/no-redundant-usestate-type": "warn",
+		"nextkit/lucide-icon-suffix": "warn",
+		"nextkit/no-redirect-only-page": "warn",
 		"no-unused-vars": "warn",
 		"typescript/no-non-null-assertion": "error",
 		"typescript/no-explicit-any": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.4.1",
+	"version": "0.6.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",
@@ -15,6 +15,7 @@
 	"files": [
 		"bin",
 		"lib",
+		"skills",
 		"tsconfig",
 		"vitest",
 		"oxlintrc.json",
@@ -30,7 +31,7 @@
 		"./oxlintrc.json": "./oxlintrc.json",
 		"./oxfmtrc.json": "./oxfmtrc.json",
 		"./tier-b.json": "./tier-b.json",
-		"./oxlint-plugin": "./lib/oxlint-plugins/base-ui.js",
+		"./oxlint-plugin": "./lib/oxlint-plugins/index.js",
 		"./tsconfig": "./tsconfig/nextjs.json",
 		"./tsconfig/base.json": "./tsconfig/base.json",
 		"./tsconfig/nextjs.json": "./tsconfig/nextjs.json",
@@ -44,6 +45,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
+		"@ast-grep/cli": "^0.44.1",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@typescript/native": "npm:typescript@^7.0.2",
 		"jsdom": "^29.1.1",

package/skills/ts-codemod.md

@@ -0,0 +1,121 @@
+# Skill: large-scale TS/TSX codemods with `nk ast-grep`
+
+You're an AI agent working in a **nextkit** site. When a change is **mechanical
+and repeats across many files** — rename an API, rewrite an import, add a prop,
+swap a call shape — don't hand-edit file by file and don't sed. Reach for
+`nk ast-grep`: the [ast-grep](https://ast-grep.github.io) binary vendored by
+`@ingram-tech/nk-dev`, which matches and rewrites by **syntax tree**, so it
+respects TS/TSX structure instead of guessing with regex.
+
+`nk ast-grep` is a thin passthrough — every argument goes straight to `ast-grep`,
+so its own `--help` / `run` / `scan` subcommands and docs all apply.
+
+## When to use it (and when not to)
+
+Use it for **syntactic, pattern-shaped** edits repeated at scale:
+
+- rewrite every `import { x } from "old"` → `"@ingram-tech/new"`
+- rename a function/method across the codebase (`foo(...)` → `bar(...)`)
+- add/rename/remove a prop on a component or an option on a call
+- change a call's argument shape (positional → options object, etc.)
+
+Do **not** use it when the change needs **type information or semantics** —
+"rename this symbol only where it refers to *this* declaration", "update every
+caller whose argument is a `User`". ast-grep sees syntax, not types, so it can't
+tell two identically-named things apart. For type-driven refactors use the TS
+language service (editor rename), `tsc`, or a type-aware tool (`ts-morph`). For a
+one-off edit in one file, just edit the file.
+
+## The workflow — always search, preview, then apply
+
+1. **Search first — never rewrite blind.** See what the pattern matches:
+
+   ```bash
+   nk ast-grep run -p 'useOldHook($$$ARGS)' -l tsx
+   ```
+
+   Read the hits. If it matches too much or too little, tighten the pattern
+   before going further. A syntactic pattern over-matches easily.
+
+2. **Preview the rewrite** (prints a diff, writes nothing without `-U`):
+
+   ```bash
+   nk ast-grep run -p 'useOldHook($$$ARGS)' -r 'useNewHook($$$ARGS)' -l tsx
+   ```
+
+3. **Apply** once the diff is exactly right (`-U` / `--update-all`):
+
+   ```bash
+   nk ast-grep run -p 'useOldHook($$$ARGS)' -r 'useNewHook($$$ARGS)' -l tsx -U
+   ```
+
+4. **Normalise, then verify.** ast-grep's output isn't house-formatted and the
+   edit is unchecked. Always follow with:
+
+   ```bash
+   nk format        # oxfmt — reflow the rewritten code
+   nk type-check    # tsc — did the rewrite actually type-check?
+   nk check         # oxlint + format-verify + knip
+   ```
+
+   Then read the full diff yourself. Treat a codemod as unverified until the
+   type-checker and your own eyes have passed over it.
+
+## Pattern syntax you need
+
+- **`$A`, `$FOO`** — a metavariable: matches one named node. Same name used twice
+  must match the same code (`$A === $A`). Uppercase/underscore names.
+- **`$$$ARGS`** — matches **zero or more** nodes (argument lists, statements,
+  JSX children). This is what makes rewrites arity-agnostic.
+- **`-l ts` / `-l tsx`** — the language. Use `tsx` for anything with JSX (most of
+  a Next.js `app/`), `ts` for plain `.ts`. Getting this wrong makes patterns
+  silently fail to parse.
+- **`-p` pattern**, **`-r` rewrite**, **`-U`** apply, **`-i`** interactive
+  (approve each edit). Scope by passing paths: `nk ast-grep run ... src/app`.
+
+Example — positional arg → options object:
+
+```bash
+nk ast-grep run -l ts \
+  -p 'createClient($URL, $KEY)' \
+  -r 'createClient({ url: $URL, key: $KEY })'
+```
+
+## When a single pattern isn't enough — rule files
+
+For matches that need context ("only inside a `useEffect`", "only calls that have
+a `.then`"), one `-p` pattern won't express it. Write an ast-grep **YAML rule**
+using relational clauses (`inside`, `has`, `follows`) and `constraints`, then:
+
+```bash
+nk ast-grep scan --rule ./rule.yml       # report
+nk ast-grep scan --rule ./rule.yml -U    # apply
+```
+
+Keep that rule file **out of the committed tree** — write it to a scratch/temp
+path and delete it after. nextkit sites don't carry codemod config as repo noise;
+the rule is a throwaway for one migration, not a fixture. (An `sgconfig.yml` at
+the repo root would make `nk ast-grep` pick up committed rules — deliberately not
+part of the nextkit convention.)
+
+Minimal rule shape:
+
+```yaml
+id: rename-hook-in-effect
+language: tsx
+rule:
+  pattern: useOldHook($$$ARGS)
+  inside: { pattern: useEffect($$$) }
+fix: useNewHook($$$ARGS)
+```
+
+## Guardrails
+
+- Syntactic, not semantic — **it can and will over-match.** Search before you
+  rewrite, every time.
+- Never apply (`-U`) straight to a dirty tree you can't diff. Commit or stash
+  first so the codemod's change is the only thing in the diff.
+- Always `nk format` + `nk type-check` after applying. A green type-check is the
+  real proof the rewrite held; the diff being pretty is not.
+- If ast-grep can't cleanly express the change in one or two rules, it's probably
+  a semantic refactor — step up to a type-aware tool instead of forcing it.