@ingram-tech/nk-dev 0.13.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -21
- package/guide.md +5 -7
- package/lib/auth-next.js +60 -0
- package/lib/doctor.js +7 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @ingram-tech/nk-dev
|
|
2
2
|
|
|
3
|
-
The nextkit
|
|
4
|
-
|
|
3
|
+
The nextkit dev toolchain in one package. Everything a site needs at development
|
|
4
|
+
time, and nothing that ships to production:
|
|
5
5
|
|
|
6
6
|
- the **`nk` CLI** (`nk dev` / `format` / `lint` / `knip` / `ast-grep` / `migrations` / `check` / `type-check` / `test` / `build`, plus
|
|
7
7
|
`nk doctor`);
|
|
@@ -12,8 +12,8 @@ development time — and nothing that ships to production — lives here:
|
|
|
12
12
|
- **`nk init`**, which scaffolds a site to use all of the above.
|
|
13
13
|
|
|
14
14
|
It's a single `devDependency` and pulls the toolchain (oxlint, oxfmt, tsc,
|
|
15
|
-
vitest, jsdom, jest-dom, knip) as hard dependencies
|
|
16
|
-
|
|
15
|
+
vitest, jsdom, jest-dom, knip) as hard dependencies, so one install gives you the
|
|
16
|
+
whole stack instead of listing each tool in every project.
|
|
17
17
|
|
|
18
18
|
> **Runtime vs dev-time.** nk-dev is the *dev-time* bundle. Runtime features
|
|
19
19
|
> (`@ingram-tech/nk-email`, `nk-db`, `nk-auth`, …) stay separate packages that
|
|
@@ -33,18 +33,18 @@ bun install # the prepare script wires the git hook
|
|
|
33
33
|
| File | What |
|
|
34
34
|
| --- | --- |
|
|
35
35
|
| `.oxlintrc.json` | `extends` the shared oxlint rules (relative path — oxlint doesn't resolve package specifiers) |
|
|
36
|
-
| `.oxfmtrc.json` | a copy of the
|
|
36
|
+
| `.oxfmtrc.json` | a copy of the shipped format config (oxfmt has no `extends`) |
|
|
37
37
|
| `tsconfig.json` | `extends` `@ingram-tech/nk-dev/tsconfig/nextjs.json` + the site's own `include`/`paths` |
|
|
38
38
|
| `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` |
|
|
39
39
|
| `.githooks/pre-commit` + `prepare` script | oxfmt format-on-commit |
|
|
40
40
|
| `CLAUDE.md` | the agent-guide `@import` |
|
|
41
41
|
|
|
42
42
|
It also prints a `vitest.config.ts` snippet (`mergeConfig(nextkitTestConfig, {})`
|
|
43
|
-
from `@ingram-tech/nk-dev/vitest`) rather than writing the file
|
|
44
|
-
you test with Vitest
|
|
43
|
+
from `@ingram-tech/nk-dev/vitest`) rather than writing the file. Add it only if
|
|
44
|
+
you test with Vitest.
|
|
45
45
|
|
|
46
|
-
Everything is `extends`-based, so the
|
|
47
|
-
overridable
|
|
46
|
+
Everything is `extends`-based, so the shipped config applies by default and stays
|
|
47
|
+
overridable: layer your own rules on top, or replace a stub entirely (e.g. drop
|
|
48
48
|
in a `biome.json` instead of the oxlint/oxfmt stubs).
|
|
49
49
|
|
|
50
50
|
## The `nk` command
|
|
@@ -65,12 +65,12 @@ Point your package.json scripts at it:
|
|
|
65
65
|
}
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
`nk` shells out to the
|
|
69
|
-
tsc), so versions stay under
|
|
68
|
+
`nk` shells out to the project's own `bun x`-resolved tools (oxlint, oxfmt, Next,
|
|
69
|
+
tsc), so versions stay under your control. nk only orchestrates.
|
|
70
70
|
|
|
71
71
|
> **`nk` is optional.** It only orchestrates the standard commands; it never
|
|
72
|
-
> wraps or intercepts the Next.js build.
|
|
73
|
-
> runnable with plain `next build` / `next dev` if `nk` is removed
|
|
72
|
+
> wraps or intercepts the Next.js build. A site stays fully buildable and
|
|
73
|
+
> runnable with plain `next build` / `next dev` if `nk` is removed. See the
|
|
74
74
|
> [`nk` carve-out](https://github.com/ingram-technologies/nextkit/blob/main/docs/philosophy.md).
|
|
75
75
|
> The orchestration tests in this package check that the formatter resolves to
|
|
76
76
|
> standard oxlint/oxfmt invocations and nothing more.
|
|
@@ -92,8 +92,8 @@ tsc), so versions stay under each site's control — nk just orchestrates.
|
|
|
92
92
|
`DATABASE_URL`, then `next dev --turbopack`. No Docker, no daemon.
|
|
93
93
|
- **Plain** — otherwise just `next dev` (static/marketing sites with no DB).
|
|
94
94
|
- **`nk format` / `nk format --check`** — formats code (JS/TS/JSON/CSS) with
|
|
95
|
-
oxfmt. `--check` verifies without writing (CI). SQL isn't formatted
|
|
96
|
-
|
|
95
|
+
oxfmt. `--check` verifies without writing (CI). SQL isn't formatted; see
|
|
96
|
+
[Why no SQL formatting?](#why-no-sql-formatting).
|
|
97
97
|
- **`nk lint`** — `oxlint`.
|
|
98
98
|
- **`nk knip`** — `knip` (unused dependencies / exports / files).
|
|
99
99
|
- **`nk migrations [--check|--reseal|--ddl]`** — guard the `drizzle/` migration
|
|
@@ -132,9 +132,9 @@ tsc), so versions stay under each site's control — nk just orchestrates.
|
|
|
132
132
|
|
|
133
133
|
## Why no SQL formatting?
|
|
134
134
|
|
|
135
|
-
oxfmt
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
135
|
+
oxfmt can't format SQL, and nk-dev doesn't format it by another route either. In
|
|
136
|
+
a nextkit project the SQL is nearly all generated (drizzle migrations, `pg_dump`
|
|
137
|
+
baselines, pglite fixtures), so formatting it only churned generated files and
|
|
138
|
+
crashed on psql directives (`\restrict`) for no gain. nk-dev therefore carries no
|
|
139
|
+
`prettier` dependency; if a project has a leftover `.prettierignore`,
|
|
140
|
+
`nk doctor --fix` removes it.
|
package/guide.md
CHANGED
|
@@ -9,10 +9,9 @@ package. Stay a thin, standard Next.js app (bun · oxlint + oxfmt · strict TS).
|
|
|
9
9
|
- **Public contact/signup forms MUST use `@ingram-tech/nk-forms`** —
|
|
10
10
|
`handleFormSubmission` server-side (rate-limit → bot gate → validate →
|
|
11
11
|
escaped-email deliver → uniform 200) and `useFormSubmit` + `HoneypotInput`
|
|
12
|
-
client-side.
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
without the bot gate.
|
|
12
|
+
client-side. For guarding a *non-form* endpoint (a checkout, an authed
|
|
13
|
+
route), call nk-forms' `checkBot` / `verifyHuman` directly instead of the
|
|
14
|
+
pipeline. Never ship a public form without the bot gate.
|
|
16
15
|
- **Send email only via `@ingram-tech/nk-email`** — never add another mail client.
|
|
17
16
|
- **Never trust an external request body's shape — validate it with Zod, never
|
|
18
17
|
`as`-cast it.** Every `/api` route and webhook handler takes untrusted input;
|
|
@@ -151,12 +150,11 @@ tool instead). One-off single-file edits: just edit the file.
|
|
|
151
150
|
## What nextkit provides (reach for these)
|
|
152
151
|
|
|
153
152
|
- `@ingram-tech/nk-email` — Cloudflare email: `sendEmail`, `fromAddress`
|
|
154
|
-
- `@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`
|
|
153
|
+
- `@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`. A site with its own proxy sets the `next`-preserving header with `withAuthPathHeader(request, requestHeaders)` instead (and `clearStaleSession` for the stale-cookie handshake); a site wrapping the guards redirects to `await signInTarget()` rather than the bare sign-in path
|
|
155
154
|
- `@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`
|
|
156
155
|
- `@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
|
|
157
156
|
- `@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
|
|
158
|
-
- `@ingram-tech/
|
|
159
|
-
- `@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
|
|
157
|
+
- `@ingram-tech/nk-forms` — the public contact/signup submission pipeline: `handleFormSubmission` (rate-limit → bot gate → validate → escaped-email deliver → uniform 200), `renderNotificationEmail`, `mintFormToken`, and `useFormSubmit` / `HoneypotInput` (`/react`). It owns the invisible bot-protection layers too (honeypot + signed timing token + Vercel BotID); `verifyHuman` / `checkBot` are exported from the root for non-form endpoints
|
|
160
158
|
- `@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`
|
|
161
159
|
- `@ingram-tech/nk-marketing` — Postgres-backed marketing & lifecycle email: contacts + consent, newsletter broadcast audiences, and idempotent triggered campaigns, with RFC 8058 one-click unsubscribe
|
|
162
160
|
- `@ingram-tech/nk-seo` — SEO toolkit: metadata factory, JSON-LD builders, sitemap/robots routes, hreflang + canonical links, and an OG image template
|
package/lib/auth-next.js
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { existsSync, readFileSync, readdirSync } from "node:fs";
|
|
2
|
+
import { join, relative, resolve } from "node:path";
|
|
3
|
+
|
|
4
|
+
// `next` preservation in nk-auth is split across two layers: a proxy sets the
|
|
5
|
+
// `x-nk-auth-path` request header (via `createAuthMiddleware` or
|
|
6
|
+
// `withAuthPathHeader`), and `createAuthHelpers`' guards read it to build
|
|
7
|
+
// `?next=` when they redirect to sign-in. A site that binds the helpers but
|
|
8
|
+
// never sets the header loses `next` with no error: every "sign in to see this
|
|
9
|
+
// page" lands on the default page. The runtime warns once outside production;
|
|
10
|
+
// this check catches it before the site is even run. Textual, like the
|
|
11
|
+
// endpoint-shadow check: we grep the site's sources, never execute them.
|
|
12
|
+
|
|
13
|
+
const SOURCE_DIRS = ["src", "app", "lib", "proxy.ts", "middleware.ts"];
|
|
14
|
+
const SOURCE_FILES = /\.(ts|tsx|js|jsx|mjs)$/;
|
|
15
|
+
const SKIP_DIRS = new Set(["node_modules", ".next", "dist", "build"]);
|
|
16
|
+
|
|
17
|
+
/** Every source file under the site's app-code roots, relative to `cwd`. */
|
|
18
|
+
function sourceFiles(cwd) {
|
|
19
|
+
const out = [];
|
|
20
|
+
const walk = (dir) => {
|
|
21
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
22
|
+
if (entry.isDirectory()) {
|
|
23
|
+
if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith("."))
|
|
24
|
+
walk(join(dir, entry.name));
|
|
25
|
+
} else if (SOURCE_FILES.test(entry.name) && !/\.test\./.test(entry.name)) {
|
|
26
|
+
out.push(relative(cwd, join(dir, entry.name)));
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
for (const root of SOURCE_DIRS) {
|
|
31
|
+
const full = resolve(cwd, root);
|
|
32
|
+
if (!existsSync(full)) continue;
|
|
33
|
+
if (SOURCE_FILES.test(root)) out.push(root);
|
|
34
|
+
else walk(full);
|
|
35
|
+
}
|
|
36
|
+
return out;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The "helpers bound, header never set" finding, or nothing. Silent on sites
|
|
41
|
+
* without `createAuthHelpers`, since they have no guard to lose `next` from.
|
|
42
|
+
*/
|
|
43
|
+
export function authNextFindings(cwd) {
|
|
44
|
+
let boundIn = null;
|
|
45
|
+
let wired = false;
|
|
46
|
+
for (const file of sourceFiles(cwd)) {
|
|
47
|
+
const src = readFileSync(resolve(cwd, file), "utf8");
|
|
48
|
+
if (!boundIn && /\bcreateAuthHelpers\s*\(/.test(src)) boundIn = file;
|
|
49
|
+
if (/\b(createAuthMiddleware|withAuthPathHeader)\s*\(/.test(src)) wired = true;
|
|
50
|
+
if (boundIn && wired) return [];
|
|
51
|
+
}
|
|
52
|
+
if (!boundIn) return [];
|
|
53
|
+
return [
|
|
54
|
+
{
|
|
55
|
+
id: "auth:next-unwired",
|
|
56
|
+
level: "warn",
|
|
57
|
+
message: `\`${boundIn}\` binds createAuthHelpers, but nothing sets the x-nk-auth-path header — its guards redirect to the bare sign-in path and \`next\` is lost. Mount createAuthMiddleware, or call withAuthPathHeader(request, requestHeaders) from "@ingram-tech/nk-auth/middleware" in your proxy.`,
|
|
58
|
+
},
|
|
59
|
+
];
|
|
60
|
+
}
|
package/lib/doctor.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { resolve } from "node:path";
|
|
3
|
+
import { authNextFindings } from "./auth-next.js";
|
|
3
4
|
import { authShadowFindings } from "./auth-shadow.js";
|
|
4
5
|
import { SUPERSEDED_DEPS } from "./drift.js";
|
|
5
6
|
import {
|
|
@@ -312,6 +313,10 @@ export function findings(cwd) {
|
|
|
312
313
|
// 11. No page/route under app/auth/ shadows a Better Auth endpoint.
|
|
313
314
|
out.push(...authShadowFindings(cwd));
|
|
314
315
|
|
|
316
|
+
// 12. If nk-auth's server guards are bound, something sets the header they
|
|
317
|
+
// need to preserve `next`.
|
|
318
|
+
out.push(...authNextFindings(cwd));
|
|
319
|
+
|
|
315
320
|
return out;
|
|
316
321
|
}
|
|
317
322
|
|
|
@@ -386,7 +391,8 @@ function migrationFindings(cwd) {
|
|
|
386
391
|
* dependencies, oxlint/tsconfig extends, the CLAUDE.md guide import, stale knip
|
|
387
392
|
* ignores, forbidden schema-applying drizzle-kit scripts, Prettier leftovers,
|
|
388
393
|
* a missing or thin `ci` script, an unsealed or unmodelled-DDL-carrying migration chain, a
|
|
389
|
-
* page under app/auth/ shadowing a Better Auth endpoint
|
|
394
|
+
* page under app/auth/ shadowing a Better Auth endpoint, nk-auth guards bound
|
|
395
|
+
* without the proxy header that preserves `next`).
|
|
390
396
|
* With `--fix`, apply every auto-fixable finding, then remind
|
|
391
397
|
* to reinstall.
|
|
392
398
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ingram-tech/nk-dev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
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.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|