@ingram-tech/nk-dev 0.17.0 → 0.18.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 CHANGED
@@ -84,7 +84,9 @@ tsc), so versions stay under your control. nk only orchestrates.
84
84
  import, a stale `.prettierignore`, an unsealed migration chain and the DDL in
85
85
  it drizzle can't model, a page under `app/auth/` shadowing a Better Auth
86
86
  endpoint — static segments beat the `[...all]` catch-all, so such a page
87
- silently 405s the endpoint); `--fix` applies the auto-fixable findings.
87
+ silently 405s the endpoint, a page or layout whose `openGraph` carries no
88
+ image — its own object replaces the inherited one, so the card unfurls as a
89
+ blank placeholder); `--fix` applies the auto-fixable findings.
88
90
  - **`nk dev`** — start the Next dev server on the golden-path local database
89
91
  (see [`db-package.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/db-package.md)):
90
92
  - **PGlite** — if `@ingram-tech/nk-db`'s `nk-pglite-dev` bin resolves, hand off
package/guide.md CHANGED
@@ -177,7 +177,7 @@ tool instead). One-off single-file edits: just edit the file.
177
177
  nk-auth's migration chain, and the order on every site is bump, `db:migrate`
178
178
  against the target database, then deploy. `createAuthHelpers` refuses to
179
179
  serve a session while the recorded chain lags the installed package.
180
- Presets: 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
180
+ 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
181
181
  - `@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`
182
182
  - `@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
183
183
  - `@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
package/lib/doctor.js CHANGED
@@ -3,6 +3,7 @@ import { resolve } from "node:path";
3
3
  import { authNextFindings } from "./auth-next.js";
4
4
  import { authShadowFindings } from "./auth-shadow.js";
5
5
  import { authVersionFindings } from "./auth-version.js";
6
+ import { ogImageFindings } from "./og-image.js";
6
7
  import { SUPERSEDED_DEPS } from "./drift.js";
7
8
  import {
8
9
  SEAL_FILE,
@@ -339,6 +340,9 @@ export function findings(cwd) {
339
340
  // released against — its chain carries the schema that version needs.
340
341
  out.push(...authVersionFindings(cwd));
341
342
 
343
+ // 14. No page/layout declares an Open Graph card without an image in reach.
344
+ out.push(...ogImageFindings(cwd));
345
+
342
346
  return out;
343
347
  }
344
348
 
@@ -0,0 +1,81 @@
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
+
4
+ // Next attaches an `opengraph-image.*` file to the segment that declares it,
5
+ // and a page's or layout's own `openGraph` object replaces the inherited one
6
+ // rather than merging into it. So a metadata object that sets `openGraph` (or
7
+ // `twitter`) without `images` emits a card with title, description and
8
+ // `summary_large_image` but no `og:image` unless the image file sits in that
9
+ // same directory, and every unfurler renders that as a blank placeholder. The
10
+ // build is green and the home page, next to the image, looks right; only the
11
+ // routes people actually paste (login, docs, tools) are broken. We read the
12
+ // metadata declaration textually, as auth-shadow reads better-auth's dist.
13
+
14
+ const PAGE_OR_LAYOUT = /^(layout|page)\.(tsx|jsx|ts|js)$/;
15
+ const IMAGE_FILE = /^opengraph-image\d*\.(tsx|jsx|ts|js|png|jpe?g|gif)$/;
16
+ const DECLARES_CARD = /\b(openGraph|twitter)\s*:/;
17
+ const CARRIES_IMAGE = /\bimages\s*[:,}]|\bogImageMetadata\s*\(/;
18
+
19
+ /** The site's app directory, or null when it has none. */
20
+ function findAppDir(cwd) {
21
+ for (const rel of ["src/app", "app"]) {
22
+ const dir = resolve(cwd, rel);
23
+ if (existsSync(dir)) return dir;
24
+ }
25
+ return null;
26
+ }
27
+
28
+ /**
29
+ * Walk the route tree collecting page/layout files that declare a card
30
+ * without an image in reach. `nearest` is the closest ancestor (or own)
31
+ * directory holding an image file, for the hint. `_private` folders and
32
+ * `@slot` trees are skipped: a slot's metadata resolution is its own story.
33
+ */
34
+ function collect(cwd, dir, segments, nearest, out) {
35
+ const entries = readdirSync(dir, { withFileTypes: true });
36
+ const ownImage = entries.find((e) => e.isFile() && IMAGE_FILE.test(e.name));
37
+ const here = ownImage ? join(dir, ownImage.name) : null;
38
+
39
+ for (const entry of entries) {
40
+ const full = join(dir, entry.name);
41
+ if (entry.isDirectory()) {
42
+ if (entry.name === "node_modules") continue;
43
+ if (entry.name.startsWith("_") || entry.name.startsWith("@")) continue;
44
+ const next = /^\(.*\)$/.test(entry.name)
45
+ ? segments
46
+ : [...segments, entry.name];
47
+ collect(cwd, full, next, here ?? nearest, out);
48
+ continue;
49
+ }
50
+ if (!PAGE_OR_LAYOUT.test(entry.name)) continue;
51
+ if (here) continue; // the file convention wins in its own segment
52
+ const src = readFileSync(full, "utf8");
53
+ if (!DECLARES_CARD.test(src) || CARRIES_IMAGE.test(src)) continue;
54
+ out.push({
55
+ file: full.slice(cwd.length + 1),
56
+ route: `/${segments.join("/")}`,
57
+ nearest: nearest ? nearest.slice(cwd.length + 1) : null,
58
+ });
59
+ }
60
+ }
61
+
62
+ /**
63
+ * Findings for OG cards that advertise an image they don't carry. Silent on
64
+ * sites without an app directory.
65
+ */
66
+ export function ogImageFindings(cwd) {
67
+ const appDir = findAppDir(cwd);
68
+ if (!appDir) return [];
69
+ const hits = [];
70
+ collect(cwd, appDir, [], null, hits);
71
+ return hits.map(({ file, route, nearest }) => {
72
+ const fix = nearest
73
+ ? `it inherits nothing from \`${nearest}\`: a segment's own \`openGraph\` replaces the inherited one. Spread \`images\` into the object (nk-seo's \`ogImageMetadata\`, or \`createMetadata\` with \`defaultImage\`), or move the image file next to it`
74
+ : "no `opengraph-image.*` exists in its directory or above. Add one at the app root (only there does it serve at a stable `/opengraph-image` URL; under a route group Next appends a hash) or set `images` in the object";
75
+ return {
76
+ id: `og:image-missing:${route}`,
77
+ level: "error",
78
+ message: `\`${file}\` declares an Open Graph card with no image, so \`${route}\` unfurls as a blank placeholder in Slack, LinkedIn and iMessage: ${fix}.`,
79
+ };
80
+ });
81
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.17.0",
3
+ "version": "0.18.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",