@ingram-tech/nk-dev 0.2.0 → 0.2.4

package/README.md

@@ -15,7 +15,7 @@ vitest, jsdom, jest-dom, knip) as hard dependencies — so one install gives you
 the whole stack instead of re-listing each tool per site.
 
 > **Runtime vs dev-time.** nk-dev is the *dev-time* bundle. Runtime features
-> (`@ingram-tech/email`, `nk-db`, `nk-auth`, …) stay separate packages that
+> (`@ingram-tech/nk-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).
 
@@ -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

@@ -9,8 +9,11 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
 - **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
+- **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;
+  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,13 +51,33 @@ 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`
-- `@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/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-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/newsletter` — Supabase newsletter: subscribe / send, 1-click unsubscribe
+- `@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-dev` — the whole dev toolchain in one devDependency: the `nk` command (`nk dev` boots local PGlite via `@ingram-tech/nk-db` if installed, then Next; plus `nk format` / `lint` / `knip` / `check` / `type-check` / `build`), the shared oxlint + oxfmt / TypeScript / Vitest config, knip, the oxfmt format-on-commit hook, and this guide. `nk check` runs every fast checker (oxlint, oxfmt, SQL, knip) in one gate. `nk init` scaffolds a site to use it all.
 
 For detail on any package, read its README in `node_modules/@ingram-tech/<pkg>/`.

package/lib/dev.js

@@ -26,8 +26,8 @@ function hasPgliteDev() {
  * (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.
+ * `nk dev` boots no external database service — when nk-db is installed it runs
+ * local PGlite (Postgres-in-WASM), and a site with no database just runs Next.
  */
 export function dev(extraArgs = []) {
 	const command = hasPgliteDev()

package/lib/format.js

@@ -8,14 +8,14 @@ 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).
+// (matches the house tab style + the PostgreSQL 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,
+ * oxfmt can't format. Prettier + prettier-plugin-sql are bundled with nk-dev,
  * 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.
  */

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.4",
 	"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/tier-b.json

@@ -5,10 +5,6 @@
 			"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"],

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,