@ingram-tech/nk-dev 0.11.0 → 0.11.1

package/README.md

@@ -82,7 +82,9 @@ tsc), so versions stay under each site's control — nk just orchestrates.
 - **`nk doctor [--fix]`** — report drift from the canonical nk-dev toolchain
   (superseded deps, config `extends`, package.json scripts, the agent-guide
   import, a stale `.prettierignore`, an unsealed migration chain and the DDL in
-  it drizzle can't model); `--fix` applies the auto-fixable findings.
+  it drizzle can't model, a page under `app/auth/` shadowing a Better Auth
+  endpoint — static segments beat the `[...all]` catch-all, so such a page
+  silently 405s the endpoint); `--fix` applies the auto-fixable findings.
 - **`nk dev`** — start the Next dev server on the golden-path local database
   (see [`db-package.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/db-package.md)):
   - **PGlite** — if `@ingram-tech/nk-db`'s `nk-pglite-dev` bin resolves, hand off

package/bin/nk.js

@@ -17,7 +17,8 @@ Commands:
                       oxfmt / TypeScript / Vitest config, the format-on-commit
                       hook, and the agent-guide import. Skips files that exist.
   doctor [--fix]      Report drift from the canonical nk-dev toolchain (scripts,
-                      superseded deps, config extends, guide import); --fix applies.
+                      superseded deps, config extends, guide import, auth pages
+                      shadowing Better Auth endpoints); --fix applies.
   dev                 Start the Next dev server (Turbopack). Boots local PGlite
                       first when @ingram-tech/nk-db is installed (no Docker).
   format [--check]    Format code with oxfmt. --check verifies without writing.

package/guide.md

@@ -66,10 +66,10 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
   (`uuid("id").primaryKey().default(sql\`uuidv7()\`)`) and Better Auth gets
   `advanced.database.generateId: false` so the DB mints ids; below 18 — and in
   the nk-auth README's canonical example — pass
-  `advanced.database.generateId: uuidGenerateId` (JS-minted UUIDv7 from
-  `@ingram-tech/nk-auth`) instead. Either way, never Better Auth's default JS
+  `advanced.database.generateId: uuidv7` (JS-minted UUIDv7 from `id758`;
+  `@ingram-tech/nk-auth` re-exports it as `uuidGenerateId`) instead. Either way, never Better Auth's default JS
   nanoid. Ids that cross a **public contract** are skinned to `prefix_base58`
-  via `@ingram-tech/nk-db/id` (`createIdRegistry`) — never expose a raw UUID.
+  via `id758` / `@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
@@ -139,12 +139,12 @@ tool instead). One-off single-file edits: just edit the file.
 
 - `@ingram-tech/nk-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). Don't hand-roll session reads or auth middleware — bind `createAuthHelpers` (`getUser` / `requireUser` / `redirectIfAuthenticated`, from `@ingram-tech/nk-auth/server`) and gate routes with the loop-safe `createAuthMiddleware`
-- `@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-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 (the standalone `id758` package) 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); 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-i18n` — type-safe, English-as-key i18n: the English source text *is* the key (no `en.json`), ICU MessageFormat, colocated JSON catalogs, plus **locale URL routing** (`defineLocaleRouting` + a fixed URL→account→cookie→`Accept-Language`→country precedence, wired to Next at `/next`). A URL that names a locale must serve it with a 200 — never redirect `?hl=fr` away, or every hreflang annotation on the site points at a URL that doesn't serve the language it claims. See `docs/i18n-routing.md`
 - `@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

package/lib/artifacts.js

@@ -17,7 +17,7 @@ const GENERATED_DIRECTORIES = [
 ];
 
 /** Prefixes (posix-normalised) that `tsc` error locations may fall inside. */
-export const TYPE_CHECK_INPUT_PREFIXES = GENERATED_DIRECTORIES.filter(
+const TYPE_CHECK_INPUT_PREFIXES = GENERATED_DIRECTORIES.filter(
 	(entry) => entry.typeCheckInput,
 ).map((entry) => entry.path);
 

package/lib/auth-shadow.js

@@ -0,0 +1,150 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+// In the App Router a static segment always beats a catch-all, so a page (or
+// route.ts) under `app/auth/` whose path matches a Better Auth endpoint
+// silently shadows it: GETs render the page, POSTs to the endpoint return 405,
+// and nothing at build time says so. The endpoint list is derived textually
+// from better-auth's dist (grep for `createAuthEndpoint("...")`) — we never
+// load or execute site or dependency code just to read a set of strings.
+
+const PAGE_FILES = /^page\.(tsx|jsx|ts|js)$/;
+const ROUTE_FILES = /^route\.(ts|js)$/;
+const ENDPOINT_RE = /createAuthEndpoint\(\s*"([^"]+)"/g;
+
+/** The `app/auth/[...all]` mount dir, or null when the site has no auth mount. */
+function findMount(cwd) {
+	for (const appDir of ["src/app", "app"]) {
+		const catchAll = resolve(cwd, appDir, "auth", "[...all]");
+		for (const ext of ["ts", "js", "tsx", "jsx"]) {
+			if (existsSync(join(catchAll, `route.${ext}`))) {
+				return { appDir, authDir: resolve(cwd, appDir, "auth") };
+			}
+		}
+	}
+	return null;
+}
+
+/** better-auth's dist dir resolved from the site, or null when not installed. */
+function betterAuthDist(cwd) {
+	try {
+		const require = createRequire(resolve(cwd, "package.json"));
+		const pkg = require.resolve("better-auth/package.json");
+		return join(dirname(pkg), "dist");
+	} catch {
+		return null;
+	}
+}
+
+/** All `createAuthEndpoint("...")` paths in the `.mjs` files under `dir`. */
+function grepEndpoints(dir, recurse) {
+	if (!existsSync(dir)) return [];
+	const paths = new Set();
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (recurse) for (const p of grepEndpoints(full, true)) paths.add(p);
+			continue;
+		}
+		if (!entry.name.endsWith(".mjs")) continue;
+		const src = readFileSync(full, "utf8");
+		for (const m of src.matchAll(ENDPOINT_RE)) paths.add(m[1]);
+	}
+	return [...paths];
+}
+
+/**
+ * Walk `app/auth/**` collecting the page/route files that claim a static URL,
+ * as `{ file, segments }` with `file` relative to `cwd`. Skips the `[...all]`
+ * catch-all itself, `_private` folders, and `@slot` parallel-route trees (a
+ * slot renders alongside the layout rather than owning the URL segment, so we
+ * conservatively leave those trees to the human); `(group)` segments don't
+ * appear in the URL and are dropped.
+ */
+function collectRoutes(cwd, dir, segments, out) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "[...all]") continue;
+			if (entry.name.startsWith("_") || entry.name.startsWith("@")) continue;
+			const next = /^\(.*\)$/.test(entry.name)
+				? segments
+				: [...segments, entry.name];
+			collectRoutes(cwd, full, next, out);
+			continue;
+		}
+		if (!PAGE_FILES.test(entry.name) && !ROUTE_FILES.test(entry.name)) continue;
+		if (segments.length === 0) continue; // `/auth` itself can't match an endpoint
+		out.push({ file: full.slice(cwd.length + 1), segments });
+	}
+}
+
+/**
+ * Whether a page's segments match an endpoint path: same segment count, where
+ * an endpoint `:param` matches any page segment and a page `[param]` (or
+ * catch-all) matches any endpoint segment.
+ */
+function shadows(segments, endpoint) {
+	const eps = endpoint.split("/").filter(Boolean);
+	if (eps.length !== segments.length) return false;
+	return eps.every((ep, i) => {
+		const seg = segments[i];
+		if (ep.startsWith(":")) return true;
+		if (/^\[.*\]$/.test(seg)) return true;
+		return seg === ep;
+	});
+}
+
+/**
+ * Findings for Better Auth endpoint shadowing. Silent on sites without an
+ * `app/auth/[...all]` mount or without better-auth installed. Core endpoints
+ * (dist/api/routes) shadow as errors; plugin endpoints (dist/plugins) as
+ * warnings, since only enabled plugins are live and we can't tell which those
+ * are without executing the site's auth config.
+ */
+export function authShadowFindings(cwd) {
+	const mount = findMount(cwd);
+	if (!mount) return [];
+	const dist = betterAuthDist(cwd);
+	if (!dist) return [];
+
+	const core = grepEndpoints(join(dist, "api", "routes"), false);
+	if (core.length === 0) {
+		return [
+			{
+				id: "auth:shadow-check-skipped",
+				level: "warn",
+				message:
+					"could not derive Better Auth's endpoint list from better-auth/dist/api/routes (layout changed?) — the endpoint-shadowing check was skipped",
+			},
+		];
+	}
+	const plugin = grepEndpoints(join(dist, "plugins"), true);
+
+	const routes = [];
+	collectRoutes(cwd, mount.authDir, [], routes);
+
+	const out = [];
+	for (const { file, segments } of routes) {
+		const routePath = `/${segments.join("/")}`;
+		const hit = core.find((ep) => shadows(segments, ep));
+		if (hit) {
+			out.push({
+				id: `auth:endpoint-shadow:${routePath}`,
+				level: "error",
+				message: `\`${file}\` shadows Better Auth's \`/auth${hit}\` endpoint — a static segment beats the \`[...all]\` catch-all, so POSTs to it return 405 and the auth flow silently breaks. Rename the page (the precedent: the reset page is \`/auth/set-password\` because \`/auth/reset-password\` is taken).`,
+			});
+			continue;
+		}
+		const pluginHit = plugin.find((ep) => shadows(segments, ep));
+		if (pluginHit) {
+			out.push({
+				id: `auth:endpoint-shadow-plugin:${routePath}`,
+				level: "warn",
+				message: `\`${file}\` would shadow the Better Auth plugin endpoint \`/auth${pluginHit}\` — only a problem if the site enables that plugin, but a rename now avoids the 405 later.`,
+			});
+		}
+	}
+	return out;
+}

package/lib/doctor.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { authShadowFindings } from "./auth-shadow.js";
 import { SUPERSEDED_DEPS } from "./drift.js";
 import {
 	SEAL_FILE,
@@ -269,6 +270,9 @@ export function findings(cwd) {
 	// 9. The migration chain is sealed, and its unmodelled DDL is declared.
 	out.push(...migrationFindings(cwd));
 
+	// 10. No page/route under app/auth/ shadows a Better Auth endpoint.
+	out.push(...authShadowFindings(cwd));
+
 	return out;
 }
 
@@ -329,7 +333,8 @@ function migrationFindings(cwd) {
  * `nk doctor [--fix]` — report drift from the canonical nk-dev model (scripts,
  * dependencies, oxlint/tsconfig extends, the CLAUDE.md guide import, stale knip
  * ignores, forbidden schema-applying drizzle-kit scripts, a dead
- * .prettierignore, an unsealed or unmodelled-DDL-carrying migration chain).
+ * .prettierignore, an unsealed or unmodelled-DDL-carrying migration chain, a
+ * page under app/auth/ shadowing a Better Auth endpoint).
  * With `--fix`, apply every auto-fixable finding, then remind
  * to reinstall.
  */

package/lib/oxlint-plugins/no-crypto-random-uuid.js

@@ -8,7 +8,7 @@
 // invisible until the table is large, which is exactly when it is expensive to
 // undo.
 //
-// The mint is `uuidGenerateId()` from `@ingram-tech/nk-db/id`, already typed
+// The mint is `uuidv7()` from `id758` (re-exported by `@ingram-tech/nk-db/id`), already typed
 // `Uuid`. Most rows need no mint at all: `uuid("id").primaryKey().default(sql`
 // `uuidv7()`)` lets the database do it, and the app only mints when it needs the
 // id *before* the insert (a client-chosen document PK it must also use as the
@@ -17,7 +17,7 @@
 // Deliberately not autofixable. The right replacement depends on what the value
 // is, and one of the answers is "leave it alone":
 //
-//   - a stored id            -> uuidGenerateId(), or drop it for the column default
+//   - a stored id            -> uuidv7(), or drop it for the column default
 //   - a bearer token / nonce -> keep crypto.randomUUID()
 //
 // v7 is the *wrong* choice for a secret. It spends 48 bits on a millisecond
@@ -77,7 +77,7 @@ const noCryptoRandomUuid = {
 		},
 		messages: {
 			cryptoRandomUuid:
-				"`crypto.randomUUID()` is UUIDv4; stored ids are UUIDv7. Mint with `uuidGenerateId()` from `@ingram-tech/nk-db/id`, or omit the id and let the `uuidv7()` column default apply. If this is a bearer token or nonce, keep v4 and add `// oxlint-disable-next-line nextkit/no-crypto-random-uuid -- <reason>`.",
+				"`crypto.randomUUID()` is UUIDv4; stored ids are UUIDv7. Mint with `uuidv7()` from `id758` (re-exported by `@ingram-tech/nk-db/id`), or omit the id and let the `uuidv7()` column default apply. If this is a bearer token or nonce, keep v4 and add `// oxlint-disable-next-line nextkit/no-crypto-random-uuid -- <reason>`.",
 		},
 	},
 	create(context) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.11.0",
+	"version": "0.11.1",
 	"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,14 +45,14 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ast-grep/cli": "^0.45.0",
+		"@ast-grep/cli": "^0.45.1",
 		"@testing-library/dom": "^10.4.1",
-		"@testing-library/jest-dom": "^7.0.0",
+		"@testing-library/jest-dom": "^7.0.1",
 		"@typescript/native": "npm:typescript@^7.0.2",
 		"jsdom": "^30.0.1",
-		"knip": "^6.31.0",
-		"oxfmt": "^0.61.0",
-		"oxlint": "^1.76.0",
+		"knip": "^6.32.2",
+		"oxfmt": "^0.63.0",
+		"oxlint": "^1.78.0",
 		"typescript": "npm:@typescript/typescript6@^6.0.2",
 		"vitest": "^4.1.10"
 	},