@ingram-tech/nk-dev 0.12.2 → 0.13.1

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  # @ingram-tech/nk-dev
2
2
 
3
- The nextkit **dev toolchain in one package**. Everything a site needs at
4
- development time — and nothing that ships to production — lives here:
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 — so one install gives you
16
- the whole stack instead of re-listing each tool per site.
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 house format config (oxfmt has no `extends`) |
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 — add it only if
44
- you test with Vitest (many sites use `bun:test`).
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 house config is enforced by default but
47
- overridable — layer your own rules on top, or replace a stub entirely (e.g. drop
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 site's own `bun x`-resolved tools (oxlint, oxfmt, Next,
69
- tsc), so versions stay under each site's control — nk just orchestrates.
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. Every site must stay fully buildable and
73
- > runnable with plain `next build` / `next dev` if `nk` is removed — see the
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 — it's
96
- generated (drizzle migrations, `pg_dump` baselines, pglite fixtures).
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 is the formatter for code, and it can't format SQL — but nk-dev doesn't
136
- format SQL at all. The SQL in our repos is ~entirely generated (drizzle
137
- migrations, `pg_dump` baselines, pglite fixtures), so formatting it only churned
138
- generated files and crashed on psql directives (`\restrict`) for no gain. nk-dev
139
- therefore carries no `prettier` dependency; if a site has a leftover
140
- `.prettierignore`, `nk doctor --fix` removes it.
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/bin/nk.js CHANGED
@@ -34,8 +34,11 @@ Commands:
34
34
  mechanical refactors — see the codemod skill.
35
35
  check The CI gate: lint + format verify + knip (when configured)
36
36
  + the agent-guide import gate + the migration seal.
37
- type-check next typegen && tsc --noEmit. Recovers automatically when
37
+ type-check [--cold] next typegen && tsc --noEmit. Recovers automatically when
38
38
  generated types are damaged (e.g. a killed dev server).
39
+ Drops the incremental cache when the lockfile changed
40
+ since it was written (a stale cache passes against old
41
+ .d.ts); --cold always drops it.
39
42
  clean Remove regenerable build artifacts: Next's generated
40
43
  types and TypeScript incremental caches.
41
44
  test [...] vitest run (extra args passed through).
@@ -75,7 +78,7 @@ switch (cmd) {
75
78
  check();
76
79
  break;
77
80
  case "type-check":
78
- typeCheck();
81
+ typeCheck(rest);
79
82
  break;
80
83
  case "clean":
81
84
  clean();
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. It layers over `@ingram-tech/bot-protection`, which stays the
13
- primitive for guarding *non-form* endpoints (a checkout, an authed route) —
14
- call `checkBot` / `verifyHuman` directly there. Never ship a public form
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;
@@ -155,8 +154,7 @@ tool instead). One-off single-file edits: just edit the file.
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/bot-protection` — invisible form protection (honeypot + timing + Vercel BotID); the primitive nk-forms builds on, used directly only for non-form endpoints
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/artifacts.js CHANGED
@@ -1,4 +1,4 @@
1
- import { existsSync, readdirSync, rmSync } from "node:fs";
1
+ import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
 
4
4
  /**
@@ -45,6 +45,38 @@ export function listGeneratedArtifacts(cwd = process.cwd()) {
45
45
  return [...present, ...buildInfo];
46
46
  }
47
47
 
48
+ /**
49
+ * Files whose change means the dependency tree changed. The lockfile is the
50
+ * precise signal; `package.json` covers a hand edit not yet installed.
51
+ */
52
+ const DEPENDENCY_MANIFESTS = [
53
+ "bun.lock",
54
+ "bun.lockb",
55
+ "package-lock.json",
56
+ "package.json",
57
+ ];
58
+
59
+ /**
60
+ * TypeScript incremental caches older than the dependency manifests.
61
+ *
62
+ * `tsc --incremental` does not reliably notice a dependency's `.d.ts`
63
+ * changing, so after an upgrade a type-check can pass against the cached
64
+ * program while a cold run fails — the exact failure a dependency bump exists
65
+ * to catch. Keying invalidation on the lockfile catches that case without
66
+ * giving up the cache on every other run.
67
+ */
68
+ export function staleBuildInfo(cwd = process.cwd()) {
69
+ const manifests = DEPENDENCY_MANIFESTS.map((name) => join(cwd, name)).filter(
70
+ (file) => existsSync(file),
71
+ );
72
+ if (manifests.length === 0) return [];
73
+ const newest = Math.max(...manifests.map((file) => statSync(file).mtimeMs));
74
+ return listGeneratedArtifacts(cwd)
75
+ .filter((entry) => entry.owner === "tsc")
76
+ .filter((entry) => statSync(join(cwd, entry.path)).mtimeMs < newest)
77
+ .map((entry) => entry.path);
78
+ }
79
+
48
80
  /**
49
81
  * Remove generated artifacts and return the paths actually deleted. Missing
50
82
  * paths are skipped rather than reported, so this is idempotent.
package/lib/doctor.js CHANGED
@@ -1,4 +1,4 @@
1
- import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1
+ import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { resolve } from "node:path";
3
3
  import { authShadowFindings } from "./auth-shadow.js";
4
4
  import { SUPERSEDED_DEPS } from "./drift.js";
@@ -252,30 +252,82 @@ export function findings(cwd) {
252
252
  }
253
253
  }
254
254
 
255
- // 8. .prettierignore is now dead weight (nk no longer formats SQL).
256
- const prettierIgnore = resolve(cwd, ".prettierignore");
257
- if (existsSync(prettierIgnore)) {
255
+ // 8. Prettier leftovers are dead weight (nk no longer runs Prettier):
256
+ // .prettierignore, any .prettierrc*, and a "prettier" key in package.json.
257
+ for (const file of prettierFiles(cwd)) {
258
258
  out.push({
259
- id: "prettierignore",
259
+ id: `prettier:${file}`,
260
+ level: "warn",
261
+ message: `${file} is unused (nk no longer runs Prettier) — remove it`,
262
+ fix: (dir) => {
263
+ rmSync(resolve(dir, file));
264
+ return `removed ${file}`;
265
+ },
266
+ });
267
+ }
268
+ if (pkg.prettier !== undefined) {
269
+ out.push({
270
+ id: "prettier:package.json",
260
271
  level: "warn",
261
272
  message:
262
- ".prettierignore is unused (nk no longer runs Prettier) — remove it",
273
+ 'package.json has a "prettier" key (nk no longer runs Prettier) — remove it',
263
274
  fix: (dir) => {
264
- rmSync(resolve(dir, ".prettierignore"));
265
- return "removed .prettierignore";
275
+ const p = resolve(dir, "package.json");
276
+ const j = readJson(p);
277
+ delete j.prettier;
278
+ writeJson(p, j);
279
+ return 'removed "prettier" from package.json';
266
280
  },
267
281
  });
268
282
  }
269
283
 
270
- // 9. The migration chain is sealed, and its unmodelled DDL is declared.
284
+ // 9. A `ci` script exists and runs the house gate. Its full contents are
285
+ // the site's call (migrations, i18n, email catalogs, build…), so this only
286
+ // warns and never writes — but the dep-upgrade flow and pre-push both
287
+ // assume `bun run ci` is the one command that proves a change.
288
+ const ci = scripts["ci"];
289
+ if (ci === undefined) {
290
+ out.push({
291
+ id: "script:ci",
292
+ level: "warn",
293
+ message:
294
+ 'missing `ci` script — the one command that proves a change (e.g. "nk check && nk type-check && nk test")',
295
+ });
296
+ } else {
297
+ const missing = ["nk check", "nk type-check"].filter(
298
+ (cmd) => !ci.includes(cmd) && !ci.includes(`bun run ${cmd.slice(3)}`),
299
+ );
300
+ if (missing.length > 0) {
301
+ out.push({
302
+ id: "script:ci",
303
+ level: "warn",
304
+ message: `\`ci\` script does not run ${missing.map((c) => `\`${c}\``).join(" or ")} — the gate should run both`,
305
+ });
306
+ }
307
+ }
308
+
309
+ // 10. The migration chain is sealed, and its unmodelled DDL is declared.
271
310
  out.push(...migrationFindings(cwd));
272
311
 
273
- // 10. No page/route under app/auth/ shadows a Better Auth endpoint.
312
+ // 11. No page/route under app/auth/ shadows a Better Auth endpoint.
274
313
  out.push(...authShadowFindings(cwd));
275
314
 
276
315
  return out;
277
316
  }
278
317
 
318
+ /** Prettier config files present in `cwd` (relative names). */
319
+ function prettierFiles(cwd) {
320
+ let names;
321
+ try {
322
+ names = readdirSync(cwd);
323
+ } catch {
324
+ return [];
325
+ }
326
+ return names.filter(
327
+ (name) => name === ".prettierignore" || name.startsWith(".prettierrc"),
328
+ );
329
+ }
330
+
279
331
  /**
280
332
  * Findings over a `drizzle/` chain. Silent on repos without one.
281
333
  *
@@ -332,8 +384,8 @@ function migrationFindings(cwd) {
332
384
  /**
333
385
  * `nk doctor [--fix]` — report drift from the canonical nk-dev model (scripts,
334
386
  * dependencies, oxlint/tsconfig extends, the CLAUDE.md guide import, stale knip
335
- * ignores, forbidden schema-applying drizzle-kit scripts, a dead
336
- * .prettierignore, an unsealed or unmodelled-DDL-carrying migration chain, a
387
+ * ignores, forbidden schema-applying drizzle-kit scripts, Prettier leftovers,
388
+ * a missing or thin `ci` script, an unsealed or unmodelled-DDL-carrying migration chain, a
337
389
  * page under app/auth/ shadowing a Better Auth endpoint).
338
390
  * With `--fix`, apply every auto-fixable finding, then remind
339
391
  * to reinstall.
@@ -1,10 +1,15 @@
1
1
  import { checkAgentGuideImport } from "./agent-guide.js";
2
- import { cleanGeneratedArtifacts, onlyGeneratedTypeErrors } from "./artifacts.js";
2
+ import {
3
+ cleanGeneratedArtifacts,
4
+ onlyGeneratedTypeErrors,
5
+ staleBuildInfo,
6
+ } from "./artifacts.js";
3
7
  import { toolDrift } from "./drift.js";
4
8
  import { FORMATTER } from "./formatter.js";
5
9
  import { hasKnipConfig, runKnip } from "./knip.js";
6
10
  import { checkSeal } from "./migrations.js";
7
11
  import { run, runCapture, writeThrough } from "./run.js";
12
+ import { readdirSync, rmSync } from "node:fs";
8
13
 
9
14
  /** `nk lint [...]` — oxlint, with extra args passed through (e.g. `--fix`). */
10
15
  export function lint(extraArgs = []) {
@@ -75,8 +80,27 @@ function warnToolDrift() {
75
80
  * output suppresses semantic diagnostics for the whole program, so real `src/`
76
81
  * errors are hidden behind it. Recovering surfaces them and still exits
77
82
  * non-zero — it never turns a failing check into a passing one.
83
+ *
84
+ * Starts cold when the dependency tree moved. `tsc --incremental` does not
85
+ * reliably re-check a program when a dependency's `.d.ts` changes, so a
86
+ * `.tsbuildinfo` older than the lockfile is a green light that means nothing;
87
+ * it is dropped (with a note) before the run. `--cold` drops it
88
+ * unconditionally.
78
89
  */
79
- export function typeCheck() {
90
+ export function typeCheck(extraArgs = []) {
91
+ const cold = extraArgs.includes("--cold");
92
+ const stale = cold
93
+ ? cleanBuildInfoOnly()
94
+ : staleBuildInfo().map((file) => {
95
+ rmSync(file, { force: true });
96
+ return file;
97
+ });
98
+ if (stale.length > 0) {
99
+ console.error(
100
+ `nk type-check: ${cold ? "--cold" : "dependencies changed since the last run"} — removed ${stale.join(", ")}; checking from scratch.`,
101
+ );
102
+ }
103
+
80
104
  const typegen = run("next", ["typegen"]);
81
105
  if (typegen !== 0) process.exit(typegen);
82
106
 
@@ -99,6 +123,17 @@ export function typeCheck() {
99
123
  process.exit(run("tsc", ["--noEmit"]));
100
124
  }
101
125
 
126
+ /** Delete every `*.tsbuildinfo` in cwd and return the names removed. */
127
+ function cleanBuildInfoOnly() {
128
+ const removed = [];
129
+ for (const name of readdirSync(process.cwd())) {
130
+ if (!name.endsWith(".tsbuildinfo")) continue;
131
+ rmSync(name, { force: true });
132
+ removed.push(name);
133
+ }
134
+ return removed;
135
+ }
136
+
102
137
  /**
103
138
  * `nk clean` — remove build artifacts that tools regenerate from source
104
139
  * (Next's generated types, TypeScript incremental caches). Safe by
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.12.2",
3
+ "version": "0.13.1",
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",