@ingram-tech/nk-dev 0.2.0 → 0.2.3

package/README.md

@@ -34,7 +34,7 @@ bun install   # the prepare script wires the git hook
 | `.oxlintrc.json` | `extends` the shared oxlint rules (relative path — oxlint doesn't resolve package specifiers) |
 | `.oxfmtrc.json` | a copy of the house format config (oxfmt has no `extends`) |
 | `tsconfig.json` | `extends` `@ingram-tech/nk-dev/tsconfig/nextjs.json` + the site's own `include`/`paths` |
-| `knip.json` | seed config ignoring `@ingram-tech/nk-dev` (knip has no shareable config) |
+| `knip.json` | seed config (knip has no shareable config): gates on dependency/file hygiene, with unused exports/types off (noisy); ignores `@ingram-tech/nk-dev` |
 | `.githooks/pre-commit` + `prepare` script | oxfmt format-on-commit |
 | `CLAUDE.md` | the agent-guide `@import` |
 

package/guide.md

@@ -10,7 +10,10 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
   (server: `verifyHuman` → silently drop bots; client: honeypot + signed token).
   Never ship a form without it.
 - **Send email only via `@ingram-tech/email`** — never add another mail client.
-- Format/lint with **oxlint + oxfmt** via `nk` (`@ingram-tech/nk-cli`); don't
+- **Never trust an external request body's shape — validate it with Zod, never
+  `as`-cast it.** Every `/api` route and webhook handler takes untrusted input;
+  an `as` cast is a lie the type-checker can't catch at runtime.
+- Format/lint with **oxlint + oxfmt** via `nk` (`@ingram-tech/nk-dev`); don't
   reintroduce ESLint, nor Prettier for code (`nk` uses Prettier only for SQL,
   which oxfmt can't format). `nk` is optional convenience that only orchestrates
   the standard tools — the site must stay buildable with plain `next build` / `next dev`.
@@ -48,6 +51,24 @@ if your frontend fetches it as an API, it's **`/api/…`**; if a provider, cron,
 queue calls it, it's **`/internal/…`**. Never put OAuth callbacks or webhooks in
 the UI/page tree, and never expose internal plumbing under `/api/`.
 
+## Data & migrations
+
+- **IDs are UUIDv7** — never UUIDv4 / `gen_random_uuid()` / `defaultRandom()` /
+  nanoids. UUIDv7 is time-ordered, so it keeps index locality instead of
+  fragmenting the B-tree on random inserts, and one uniform id format spans every
+  table. On Postgres ≥18 the column default is native `uuidv7()`
+  (`uuid("id").primaryKey().default(sql\`uuidv7()\`)`); set Better Auth
+  `advanced.database.generateId: false` so the DB — not Better Auth's JS nanoid —
+  mints ids. Ids that cross a **public contract** are skinned to `prefix_base58`
+  via `@ingram-tech/nk-db/id` (`createIdRegistry`) — never expose a raw UUID.
+  External ids you don't mint (Stripe `cus_`, OAuth) stay `text`.
+- **Migrations don't auto-apply on deploy.** Code ships ahead of the prod schema
+  unless someone runs the migration against the target DB — a page that reads a
+  newly-added column 500s in prod until then. Apply migrations with
+  `@ingram-tech/nk-db`'s drift-aware runner (`@ingram-tech/nk-db/migrate`), which
+  surfaces the real Postgres error and pre-flights journal drift. Generate **and
+  apply** in the same step; don't leave "run the migration" as a handoff.
+
 ## What nextkit provides (reach for these)
 
 - `@ingram-tech/email` — Cloudflare email: `sendEmail`, `fromAddress`

package/lib/init.js

@@ -50,14 +50,27 @@ const TSCONFIG = {
 
 const VITEST_HINT = `import { mergeConfig } from "vitest/config";\\nimport { nextkitTestConfig } from "@ingram-tech/nk-dev/vitest";\\nexport default mergeConfig(nextkitTestConfig, {});`;
 
-// knip has no shareable config, so each site carries its own. This seed ignores
-// @ingram-tech/nk-dev: a site that runs raw tools (not the `nk` bin) gives knip
-// no way to see nk-dev as used, so without this it'd fail as an unused
-// dependency. (Sites that do call `nk` in scripts can drop it — knip will hint.)
-// Add `entry`/`ignore` as the project grows.
+// knip has no shareable config, so each site carries its own seed. The house
+// policy: gate on dependency/file hygiene (unused files/deps, unlisted,
+// unresolved) — its low-false-positive checks — and turn OFF unused
+// exports/types, which are noisy and usually intentional API surface. Run an
+// export-cleanup pass by flipping those back on when you want it.
+//
+// ignoreDependencies keeps @ingram-tech/nk-dev: knip doesn't follow the
+// relative-path `extends` in .oxlintrc/tsconfig, so a site that doesn't call the
+// `nk` bin gives knip no way to see nk-dev as used. Add `entry`/`ignore` as the
+// project grows (e.g. `scripts/**`, a self-contained `pulumi/**`).
 const KNIP = {
 	$schema: "https://unpkg.com/knip@6/schema.json",
 	ignoreDependencies: ["@ingram-tech/nk-dev"],
+	rules: {
+		exports: "off",
+		types: "off",
+		nsExports: "off",
+		nsTypes: "off",
+		enumMembers: "off",
+		duplicates: "off",
+	},
 };
 
 const PRE_COMMIT = `#!/bin/sh

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.2.0",
+	"version": "0.2.3",
 	"description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
 	"license": "MIT",
 	"type": "module",

package/tsconfig/base.json

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

package/tsconfig/nextjs.json

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