@ingram-tech/nk-dev 0.2.3 → 0.2.5

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).
 

package/bin/format-staged.mjs

@@ -8,24 +8,50 @@
  *
  * Behavior:
  *   - Only staged files are touched (never the whole tree).
+ *   - Partially staged files (staged + unstaged hunks in the same file) are
+ *     SKIPPED: `oxfmt --write` rewrites the working tree and the re-`git add`
+ *     would silently sweep the unstaged hunks into the commit.
  *   - 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";
+import { existsSync } from "node:fs";
 
 const FORMATTABLE = /\.(jsx?|mjs|cjs|tsx?|mts|cts|json|jsonc|css|graphql|gql)$/;
 
-const git = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
+const git = (args) => execFileSync("git", args, { encoding: "utf8" });
 
-const stagedFiles = git(["diff", "--cached", "--name-only", "--diff-filter=ACMRTUXB"])
-	.split("\n")
-	.filter(Boolean);
+// -z: NUL-separated, unquoted names. The default output octal-escapes any
+// non-ASCII filename ("\303\251 test.ts"), which then matches no real path and
+// silently never gets formatted or re-staged.
+const gitPathList = (args) =>
+	git([...args, "-z"])
+		.split("\0")
+		.filter(Boolean);
+
+const stagedFiles = gitPathList([
+	"diff",
+	"--cached",
+	"--name-only",
+	"--diff-filter=ACMRTUXB",
+]);
 
 if (stagedFiles.length === 0) process.exit(0);
 
-const toFormat = stagedFiles.filter((f) => FORMATTABLE.test(f));
+// Files that also carry unstaged edits: formatting + re-adding them would
+// commit hunks the developer deliberately left out (git add -p).
+const partiallyStaged = new Set(gitPathList(["diff", "--name-only"]));
+
+const formattable = stagedFiles.filter((f) => FORMATTABLE.test(f));
+const toFormat = formattable.filter((f) => !partiallyStaged.has(f));
+const skipped = formattable.filter((f) => partiallyStaged.has(f));
+if (skipped.length > 0) {
+	console.warn(
+		`[nextkit] not formatting partially staged file(s) (unstaged hunks would be committed): ${skipped.join(", ")}`,
+	);
+}
 if (toFormat.length === 0) process.exit(0);
 
 try {
@@ -40,12 +66,5 @@ try {
 }
 
 // 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;
-	}
-});
+const existing = toFormat.filter((f) => existsSync(f));
 if (existing.length > 0) git(["add", "--", ...existing]);

package/bin/nk.js

@@ -13,8 +13,8 @@ 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.
+  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 and SQL with Prettier. --check
                       verifies without writing (for CI).
   lint                Lint with oxlint.

package/guide.md

@@ -9,7 +9,7 @@ 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.
+- **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.
@@ -57,9 +57,12 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
   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`
+  (`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
+  nanoid. 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
@@ -71,11 +74,13 @@ 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/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

@@ -3,9 +3,11 @@ 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).
+ * Whether `@ingram-tech/nk-db` is resolvable from the site — the signal that
+ * its `nk-pglite-dev` bin is available. Note this is package *resolvability*,
+ * not a direct-dependency check: a transitively hoisted nk-db also flips PGlite
+ * mode on (harmless — the bin still runs `next dev`; it just also boots a local
+ * Postgres the site may not use).
  */
 function hasPgliteDev() {
 	try {
@@ -26,8 +28,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()
@@ -38,5 +40,6 @@ export function dev(extraArgs = []) {
 	}
 	// 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);
+	// Signal-killed (status null) is a failure, not a clean exit.
+	process.exit(res.status ?? (res.signal ? 1 : 0));
 }

package/lib/format.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, relative } from "node:path";
 import { FORMATTER } from "./formatter.js";
@@ -8,14 +8,20 @@ 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" };
+// (matches the house tabs/4/88 style + the PostgreSQL dialect; without the
+// explicit widths Prettier falls back to 80/2).
+const SQL_DEFAULTS = {
+	useTabs: true,
+	tabWidth: 4,
+	printWidth: 88,
+	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.
  */
@@ -24,13 +30,18 @@ export async function format({ check }) {
 	const code = run(op[0], op[1]);
 	if (code !== 0) process.exitCode = code;
 
-	await formatSql({ check });
+	if (await formatSql({ check })) process.exitCode = 1;
 }
 
-/** Format (or, with `check`, verify) every tracked `.sql` file via Prettier. */
+/**
+ * Format (or, with `check`, verify) every tracked `.sql` file via Prettier.
+ * Returns true when a check found unformatted files — the caller owns the exit
+ * code (inferring failure from the `process.exitCode` global misattributes any
+ * earlier failure to SQL).
+ */
 export async function formatSql({ check }) {
 	const files = sqlFiles();
-	if (files.length === 0) return;
+	if (files.length === 0) return false;
 
 	const prettier = require("prettier");
 	const pluginPath = require.resolve("prettier-plugin-sql");
@@ -38,6 +49,9 @@ export async function formatSql({ check }) {
 	let unformatted = 0;
 	let written = 0;
 	for (const file of files) {
+		// git ls-files lists tracked files deleted from the worktree without
+		// `git rm`; reading one would throw an unhandled ENOENT.
+		if (!existsSync(file)) continue;
 		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.
@@ -72,24 +86,25 @@ export async function formatSql({ check }) {
 		console.error(
 			`nk: ${unformatted} SQL file(s) need formatting — run \`nk format\`.`,
 		);
-		process.exitCode = 1;
-	} else if (!check && written > 0) {
+		return true;
+	}
+	if (!check && written > 0) {
 		console.log(`nk: formatted ${written} SQL file(s).`);
 	}
+	return false;
 }
 
 /** Tracked + untracked-not-ignored `.sql` files; falls back to an fs walk. */
 function sqlFiles() {
+	// -z: NUL-separated, unquoted — the default output octal-escapes non-ASCII
+	// filenames, which then match no real path.
 	const res = spawnSync(
 		"git",
-		["ls-files", "--cached", "--others", "--exclude-standard", "*.sql"],
+		["ls-files", "-z", "--cached", "--others", "--exclude-standard", "*.sql"],
 		{ encoding: "utf8" },
 	);
 	if (res.status === 0) {
-		return res.stdout
-			.split("\n")
-			.map((s) => s.trim())
-			.filter(Boolean);
+		return res.stdout.split("\0").filter(Boolean);
 	}
 	return walkSql(process.cwd());
 }

package/lib/passthrough.js

@@ -19,8 +19,7 @@ export async function check() {
 	// 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);
+	const sqlFailed = await formatSql({ check: true });
 	// knip (unused deps/exports/files). Opt-in: only when the repo has a knip
 	// config — knip has no shareable config, so absence means "not adopted".
 	const knipFailed = hasKnipConfig() ? runKnip() !== 0 : false;

package/lib/run.js

@@ -12,29 +12,9 @@ export function run(tool, args = [], opts = {}) {
 		}
 		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 ?? "";
+	// A signal-killed child (OOM, SIGSEGV) has status null — that's a failure,
+	// not a pass; `?? 0` would let a crashed linter through the CI gate.
+	return res.status ?? (res.signal ? 1 : 0);
 }
 
 /** Print an `nk:`-prefixed error and exit non-zero. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"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,13 +45,13 @@
 	"dependencies": {
 		"@testing-library/jest-dom": "^6.9.1",
 		"jsdom": "^29.1.1",
-		"knip": "^6.17.1",
-		"oxfmt": "^0.55.0",
-		"oxlint": "^1.70.0",
-		"prettier": "^3.8.3",
+		"knip": "^6.23.0",
+		"oxfmt": "^0.56.0",
+		"oxlint": "^1.71.0",
+		"prettier": "^3.9.3",
 		"prettier-plugin-sql": "^0.20.0",
 		"typescript": "^6.0.3",
-		"vitest": "^4.1.6"
+		"vitest": "^4.1.9"
 	},
 	"engines": {
 		"node": ">=20"

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"],