@ingram-tech/nk-dev 0.9.0 → 0.10.0

package/bin/nk.js

@@ -5,7 +5,7 @@ import { doctor } from "../lib/doctor.js";
 import { format } from "../lib/format.js";
 import { init } from "../lib/init.js";
 import { knip } from "../lib/knip.js";
-import { build, check, lint, test, typeCheck } from "../lib/passthrough.js";
+import { build, check, clean, lint, test, typeCheck } from "../lib/passthrough.js";
 
 const USAGE = `nk — the nextkit CLI
 
@@ -27,7 +27,10 @@ Commands:
                       mechanical refactors — see the codemod skill.
   check               The CI gate: lint + format verify + knip (when configured)
                       + the agent-guide import gate.
-  type-check          next typegen && tsc --noEmit.
+  type-check          next typegen && tsc --noEmit. Recovers automatically when
+                      generated types are damaged (e.g. a killed dev server).
+  clean               Remove regenerable build artifacts: Next's generated
+                      types and TypeScript incremental caches.
   test [...]          vitest run (extra args passed through).
   build [...]         next build (extra args passed through).
 
@@ -64,6 +67,9 @@ switch (cmd) {
 	case "type-check":
 		typeCheck();
 		break;
+	case "clean":
+		clean();
+		break;
 	case "test":
 		test(rest);
 		break;

package/lib/artifacts.js

@@ -0,0 +1,105 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Directories a tool regenerates from source, and which `tsconfig.json`
+ * typically feeds back into `tsc` (Next's typed-routes output is in `include`).
+ *
+ * That round trip is what makes them worth tracking: a killed `next dev` can
+ * leave `.next/dev/types/validator.ts` truncated mid-write, and `next typegen`
+ * does **not** repair it, so `tsc` keeps reporting a syntax error inside
+ * generated code until the directory is removed. The error points at `.next/`,
+ * so the natural reflex is to hunt a type error in `src/` that doesn't exist.
+ */
+const GENERATED_DIRECTORIES = [
+	{ path: ".next/dev/types", owner: "next typegen", typeCheckInput: true },
+	{ path: ".next/types", owner: "next typegen", typeCheckInput: true },
+];
+
+/** Prefixes (posix-normalised) that `tsc` error locations may fall inside. */
+export const TYPE_CHECK_INPUT_PREFIXES = GENERATED_DIRECTORIES.filter(
+	(entry) => entry.typeCheckInput,
+).map((entry) => entry.path);
+
+/**
+ * Every generated artifact present in `cwd`. Incremental-build caches are
+ * discovered rather than hardcoded, since `tsBuildInfoFile` renames them and a
+ * repo can carry several (`tsconfig.tsbuildinfo`, `tsconfig.slice.tsbuildinfo`).
+ *
+ * Deleting any of these is safe by construction: the owning tool rebuilds it.
+ */
+export function listGeneratedArtifacts(cwd = process.cwd()) {
+	const present = GENERATED_DIRECTORIES.filter((entry) =>
+		existsSync(join(cwd, entry.path)),
+	);
+
+	let buildInfo = [];
+	try {
+		buildInfo = readdirSync(cwd)
+			.filter((name) => name.endsWith(".tsbuildinfo"))
+			.map((name) => ({ path: name, owner: "tsc", typeCheckInput: false }));
+	} catch {
+		// An unreadable cwd is the caller's problem, not this helper's.
+	}
+
+	return [...present, ...buildInfo];
+}
+
+/**
+ * Remove generated artifacts and return the paths actually deleted. Missing
+ * paths are skipped rather than reported, so this is idempotent.
+ */
+export function cleanGeneratedArtifacts(cwd = process.cwd()) {
+	const removed = [];
+	for (const entry of listGeneratedArtifacts(cwd)) {
+		rmSync(join(cwd, entry.path), { recursive: true, force: true });
+		removed.push(entry.path);
+	}
+	return removed;
+}
+
+// Colour codes only (ESC [ … m). ESC is built from its code point rather
+// than written inline: matching it is the entire point of stripping colour, but
+// a control character inside a regex literal trips `no-control-regex`.
+const ANSI = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;]*m`, "g");
+
+/**
+ * `tsc` error headers, in both layouts: plain (piped / `--pretty false`) and
+ * pretty (a TTY, or `--pretty`).
+ */
+const ERROR_LOCATIONS = [
+	/^(.+?)\((\d+),(\d+)\): (?:error|warning) TS\d+/,
+	/^(.+?):(\d+):(\d+) - (?:error|warning) TS\d+/,
+];
+
+/** Unique file paths `tsc` reported errors in, posix-normalised. */
+export function errorFiles(output) {
+	const files = new Set();
+	for (const rawLine of String(output).split(/\r?\n/)) {
+		const line = rawLine.replace(ANSI, "");
+		for (const pattern of ERROR_LOCATIONS) {
+			const match = line.match(pattern);
+			if (!match?.[1]) continue;
+			files.add(match[1].trim().replaceAll("\\", "/").replace(/^\.\//, ""));
+			break;
+		}
+	}
+	return [...files];
+}
+
+/**
+ * Whether every error `tsc` reported sits inside generated type output — the
+ * signature of a damaged artifact rather than a source defect.
+ *
+ * Deliberately "every", not "any": a run that mixes generated and `src/` errors
+ * has real work in it, and cleaning would neither fix nor excuse those.
+ */
+export function onlyGeneratedTypeErrors(output) {
+	const files = errorFiles(output);
+	if (files.length === 0) return false;
+	return files.every((file) =>
+		TYPE_CHECK_INPUT_PREFIXES.some(
+			(prefix) => file === prefix || file.startsWith(`${prefix}/`),
+		),
+	);
+}

package/lib/oxlint-plugins/index.js

@@ -8,6 +8,7 @@ import lucideIconSuffix from "./lucide-icon-suffix.js";
 import noCryptoRandomUuid from "./no-crypto-random-uuid.js";
 import noRedirectOnlyPage from "./no-redirect-only-page.js";
 import redundantUseStateType from "./redundant-usestate-type.js";
+import satoriCss from "./satori-css.js";
 import tNoPositionalArgs from "./t-no-positional-args.js";
 import tRequiresValues from "./t-requires-values.js";
 
@@ -20,6 +21,7 @@ export default {
 		...noCryptoRandomUuid.rules,
 		...noRedirectOnlyPage.rules,
 		...redundantUseStateType.rules,
+		...satoriCss.rules,
 		...tNoPositionalArgs.rules,
 		...tRequiresValues.rules,
 	},

package/lib/oxlint-plugins/satori-css.js

@@ -0,0 +1,318 @@
+// nextkit oxlint JS plugin rule: validate inline styles in satori-rendered JSX.
+//
+// `next/og`'s `ImageResponse` types `style` as the full `React.CSSProperties`,
+// but satori implements a finite subset and **silently drops** everything else.
+// The image still renders, just wrong — which is why a render test can't catch
+// it: the PNG is valid, the shadow is simply missing. That gap is the whole
+// reason this rule exists (nk-seo README, "Open Graph image").
+//
+// Two classes of finding:
+//
+//   1. Style properties satori does not implement (`transition`, `cursor`,
+//      `backdropFilter`, the grid family, `zIndex`, `calc()`, …) — silent drops.
+//   2. The structural rules satori enforces at render time: a node with more
+//      than one child must set `display: flex` (or `none`), and text must not
+//      sit next to element siblings. These *do* throw at render; flagging them
+//      in-editor just moves the failure earlier.
+//
+// Scope: only files that are satori-bound — they import `next/og` (or
+// `@vercel/og`), or they are an `opengraph-image` / `twitter-image` file
+// convention. Sites using nk-seo's `ogImageResponse` write no satori JSX at all
+// and never trip this.
+//
+// The supported list is satori's documented one (https://github.com/vercel/satori#css)
+// plus the box-model properties yoga handles that the README's table omits. It
+// is deliberately generous: an over-wide allowlist only lowers the catch rate,
+// while a too-narrow one puts false positives into a config the whole fleet
+// inherits.
+
+/** https://github.com/vercel/satori#css, plus the yoga box-model properties. */
+const SUPPORTED = new Set([
+	// Display & position
+	"display",
+	"position",
+	"top",
+	"right",
+	"bottom",
+	"left",
+	"overflow",
+	"opacity",
+	"boxSizing",
+	"boxShadow",
+	"filter",
+	"clipPath",
+	"lineClamp",
+	"color",
+	// Box model
+	"margin",
+	"marginTop",
+	"marginRight",
+	"marginBottom",
+	"marginLeft",
+	"padding",
+	"paddingTop",
+	"paddingRight",
+	"paddingBottom",
+	"paddingLeft",
+	"width",
+	"height",
+	"minWidth",
+	"minHeight",
+	"maxWidth",
+	"maxHeight",
+	// Border
+	"border",
+	"borderTop",
+	"borderRight",
+	"borderBottom",
+	"borderLeft",
+	"borderWidth",
+	"borderTopWidth",
+	"borderRightWidth",
+	"borderBottomWidth",
+	"borderLeftWidth",
+	"borderStyle",
+	"borderTopStyle",
+	"borderRightStyle",
+	"borderBottomStyle",
+	"borderLeftStyle",
+	"borderColor",
+	"borderTopColor",
+	"borderRightColor",
+	"borderBottomColor",
+	"borderLeftColor",
+	"borderRadius",
+	"borderTopLeftRadius",
+	"borderTopRightRadius",
+	"borderBottomLeftRadius",
+	"borderBottomRightRadius",
+	// Flex
+	"flex",
+	"flexDirection",
+	"flexWrap",
+	"flexFlow",
+	"flexGrow",
+	"flexShrink",
+	"flexBasis",
+	"alignItems",
+	"alignContent",
+	"alignSelf",
+	"justifyContent",
+	"gap",
+	"rowGap",
+	"columnGap",
+	"order",
+	"aspectRatio",
+	// Font & text
+	"fontFamily",
+	"fontSize",
+	"fontWeight",
+	"fontStyle",
+	"tabSize",
+	"textAlign",
+	"textIndent",
+	"textTransform",
+	"textOverflow",
+	"textDecoration",
+	"textDecorationColor",
+	"textDecorationLine",
+	"textDecorationStyle",
+	"textShadow",
+	"textWrap",
+	"lineHeight",
+	"letterSpacing",
+	"whiteSpace",
+	"wordBreak",
+	// Background
+	"background",
+	"backgroundColor",
+	"backgroundImage",
+	"backgroundPosition",
+	"backgroundSize",
+	"backgroundClip",
+	"backgroundRepeat",
+	// Transform
+	"transform",
+	"transformOrigin",
+	// Image
+	"objectFit",
+	"objectPosition",
+	// Mask
+	"maskImage",
+	"maskPosition",
+	"maskSize",
+	"maskRepeat",
+	// Text stroke
+	"WebkitTextStroke",
+	"WebkitTextStrokeWidth",
+	"WebkitTextStrokeColor",
+	"WebkitBackgroundClip",
+	"WebkitTextFillColor",
+]);
+
+const OG_MODULES = new Set(["next/og", "@vercel/og"]);
+const IMAGE_CONVENTION = /\/(opengraph-image|twitter-image)(\.[^/]+)?\.[jt]sx$/;
+
+/** kebab-case is legal in a style object via string keys; normalize to camel. */
+const toCamelCase = (name) =>
+	name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+const satoriCss = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Restrict inline styles in satori-rendered JSX to what satori implements",
+		},
+		messages: {
+			unsupportedProperty:
+				"satori does not implement `{{property}}` — it is silently dropped from the rendered image (the PNG still comes out, just wrong, so no render test catches it). See https://github.com/vercel/satori#css for the supported subset.",
+			calc: "satori does not support `calc()` in `{{property}}` — the declaration is dropped. Compute the number in JS instead.",
+			missingFlex:
+				'This element has {{count}} children but no `display`. satori defaults every node to `display: flex`, and a node with more than one child must set it explicitly — add `display: "flex"` (or `"none"`) to make the intent survive.',
+			textWithElementSiblings:
+				"satori cannot lay out a text node next to element siblings — it throws at render. Wrap the text in its own element.",
+		},
+	},
+	create(context) {
+		const filename = context.physicalFilename || context.filename || "";
+		const isConventionFile = IMAGE_CONVENTION.test(filename.replace(/\\/g, "/"));
+		let importsOg = false;
+		/** Findings held until the whole file has been seen — the `next/og`
+		 * import is what proves the JSX is satori-bound, and a re-export or a
+		 * type-only file can carry JSX with no import at all. */
+		const findings = [];
+		const report = (descriptor) => findings.push(descriptor);
+
+		const checkStyleObject = (object) => {
+			for (const property of object.properties) {
+				if (property.type !== "Property") continue;
+				let name;
+				if (property.key.type === "Identifier" && !property.computed) {
+					name = property.key.name;
+				} else if (property.key.type === "Literal") {
+					name = String(property.key.value);
+				} else {
+					// A computed key is unknowable statically; a spread may carry
+					// anything. Silence beats guessing.
+					continue;
+				}
+				// CSS custom properties are supported (with var() and fallbacks).
+				if (name.startsWith("--")) continue;
+				const camel = toCamelCase(name);
+				if (!SUPPORTED.has(camel)) {
+					report({
+						node: property.key,
+						messageId: "unsupportedProperty",
+						data: { property: name },
+					});
+					continue;
+				}
+				if (
+					property.value.type === "Literal" &&
+					typeof property.value.value === "string" &&
+					property.value.value.includes("calc(")
+				) {
+					report({
+						node: property.value,
+						messageId: "calc",
+						data: { property: name },
+					});
+				}
+			}
+		};
+
+		// Both structural checks only count children that are *certainly*
+		// rendered. A `{cond ? <a/> : null}` child may collapse to nothing, and
+		// counting it would flag templates that lay out fine — a false positive in
+		// a rule the whole fleet inherits costs more than the miss.
+		const isCertainElement = (child) =>
+			child.type === "JSXElement" ||
+			child.type === "JSXFragment" ||
+			(child.type === "JSXExpressionContainer" &&
+				(child.expression.type === "JSXElement" ||
+					child.expression.type === "JSXFragment"));
+
+		/** Raw text, or an interpolation that can only be a string/number. */
+		const isCertainText = (child) => {
+			if (child.type === "JSXText") return child.value.trim() !== "";
+			if (child.type !== "JSXExpressionContainer") return false;
+			const expression = child.expression;
+			return (
+				(expression.type === "Literal" &&
+					typeof expression.value !== "boolean") ||
+				expression.type === "TemplateLiteral"
+			);
+		};
+
+		return {
+			ImportDeclaration(node) {
+				if (OG_MODULES.has(node.source.value)) importsOg = true;
+			},
+			JSXAttribute(node) {
+				if (node.name.type !== "JSXIdentifier" || node.name.name !== "style") {
+					return;
+				}
+				const value = node.value;
+				if (value?.type !== "JSXExpressionContainer") return;
+				if (value.expression.type !== "ObjectExpression") return;
+				checkStyleObject(value.expression);
+			},
+			JSXElement(node) {
+				const texts = node.children.filter(isCertainText);
+				const elements = node.children.filter(isCertainElement);
+				if (texts.length > 0 && elements.length > 0) {
+					report({ node, messageId: "textWithElementSiblings" });
+				}
+
+				const children = texts.length + elements.length;
+				if (children < 2) return;
+
+				// A component's own JSX is that component's business; only the
+				// intrinsic elements satori lays out carry the flex rule.
+				if (node.openingElement.name.type !== "JSXIdentifier") return;
+				if (!/^[a-z]/.test(node.openingElement.name.name)) return;
+
+				let styleObject;
+				let hasUnknownStyle = false;
+				for (const attribute of node.openingElement.attributes) {
+					if (attribute.type === "JSXSpreadAttribute") {
+						hasUnknownStyle = true;
+						continue;
+					}
+					if (attribute.name.name !== "style") continue;
+					if (attribute.value?.type !== "JSXExpressionContainer") {
+						hasUnknownStyle = true;
+					} else if (attribute.value.expression.type === "ObjectExpression") {
+						styleObject = attribute.value.expression;
+					} else {
+						hasUnknownStyle = true;
+					}
+				}
+				if (hasUnknownStyle) return;
+				const declaresDisplay = styleObject?.properties.some(
+					(property) =>
+						property.type === "Property" &&
+						!property.computed &&
+						(property.key.name === "display" ||
+							property.key.value === "display"),
+				);
+				if (declaresDisplay) return;
+				report({
+					node: node.openingElement,
+					messageId: "missingFlex",
+					data: { count: String(children) },
+				});
+			},
+			"Program:exit"() {
+				if (!importsOg && !isConventionFile) return;
+				for (const descriptor of findings) context.report(descriptor);
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "satori-css": satoriCss },
+};

package/lib/passthrough.js

@@ -1,8 +1,9 @@
 import { checkAgentGuideImport } from "./agent-guide.js";
+import { cleanGeneratedArtifacts, onlyGeneratedTypeErrors } from "./artifacts.js";
 import { toolDrift } from "./drift.js";
 import { FORMATTER } from "./formatter.js";
 import { hasKnipConfig, runKnip } from "./knip.js";
-import { run } from "./run.js";
+import { run, runCapture, writeThrough } from "./run.js";
 
 /** `nk lint [...]` — oxlint, with extra args passed through (e.g. `--fix`). */
 export function lint(extraArgs = []) {
@@ -48,13 +49,58 @@ function warnToolDrift() {
 	);
 }
 
-/** `nk type-check` — the house type-check: regenerate Next's types, then tsc. */
+/**
+ * `nk type-check` — the house type-check: regenerate Next's types, then tsc.
+ *
+ * Recovers from damaged generated types. `tsconfig.json` feeds Next's
+ * typed-routes output back into `tsc`, and a killed dev server can leave it
+ * truncated mid-write; `next typegen` does not repair it, so the same syntax
+ * error inside `.next/` survives every re-run and reads as a source defect.
+ * When *every* reported error sits in generated output, the artifacts are
+ * cleaned and the check retried once — see {@link cleanGeneratedArtifacts}.
+ *
+ * The retry matters beyond the confusing message: a syntax error in generated
+ * output suppresses semantic diagnostics for the whole program, so real `src/`
+ * errors are hidden behind it. Recovering surfaces them and still exits
+ * non-zero — it never turns a failing check into a passing one.
+ */
 export function typeCheck() {
 	const typegen = run("next", ["typegen"]);
 	if (typegen !== 0) process.exit(typegen);
+
+	const first = runCapture("tsc", ["--noEmit"]);
+	if (first.status === 0 || !onlyGeneratedTypeErrors(first.output)) {
+		// Either a pass, or errors the caller needs to read and fix themselves.
+		writeThrough(first);
+		process.exit(first.status);
+	}
+
+	const removed = cleanGeneratedArtifacts();
+	console.error(
+		`nk type-check: every error was inside generated types — removed ${removed.join(", ")} and retrying.`,
+	);
+
+	const regen = run("next", ["typegen"]);
+	if (regen !== 0) process.exit(regen);
+	// Retry with inherited stdio: this is the run whose output matters, and it
+	// keeps colour when a human is watching.
 	process.exit(run("tsc", ["--noEmit"]));
 }
 
+/**
+ * `nk clean` — remove build artifacts that tools regenerate from source
+ * (Next's generated types, TypeScript incremental caches). Safe by
+ * construction: whatever owns an artifact rebuilds it on the next run.
+ */
+export function clean() {
+	const removed = cleanGeneratedArtifacts();
+	if (removed.length === 0) {
+		console.log("nk clean: no generated artifacts found.");
+		return;
+	}
+	console.log(`nk clean: removed ${removed.join(", ")}.`);
+}
+
 /** `nk test [...]` — vitest run, with extra args passed through. */
 export function test(extraArgs = []) {
 	process.exit(run("vitest", ["run", ...extraArgs]));

package/lib/run.js

@@ -21,6 +21,40 @@ export function run(tool, args = [], opts = {}) {
 	return res.status ?? (res.signal ? 1 : 0);
 }
 
+/**
+ * Like {@link run}, but captures the tool's output instead of inheriting stdio,
+ * so a caller can inspect it before deciding what to print. Returns the exit
+ * code plus the combined output; the caller is responsible for forwarding it.
+ *
+ * Colour is left to the tool: with stdio piped there is no TTY, so tools that
+ * auto-detect print plain text — which is also what makes their output
+ * parseable.
+ */
+export function runCapture(tool, args = [], opts = {}) {
+	const res = spawnSync("bun", ["x", tool, ...args], {
+		encoding: "utf8",
+		...opts,
+	});
+	if (res.error) {
+		if (res.error.code === "ENOENT") {
+			fail("could not run `bun` — is bun installed and on PATH?");
+		}
+		throw res.error;
+	}
+	return {
+		status: res.status ?? (res.signal ? 1 : 0),
+		stdout: res.stdout ?? "",
+		stderr: res.stderr ?? "",
+		output: `${res.stdout ?? ""}${res.stderr ?? ""}`,
+	};
+}
+
+/** Forward a {@link runCapture} result to this process's stdio, unchanged. */
+export function writeThrough({ stdout, stderr }) {
+	if (stdout) process.stdout.write(stdout);
+	if (stderr) process.stderr.write(stderr);
+}
+
 /** Print an `nk:`-prefixed error and exit non-zero. */
 export function fail(message) {
 	console.error(`nk: ${message}`);

package/oxlintrc.json

@@ -13,6 +13,7 @@
 		"nextkit/t-requires-values": "error",
 		"nextkit/t-no-positional-args": "error",
 		"nextkit/no-crypto-random-uuid": "warn",
+		"nextkit/satori-css": "warn",
 		"no-unused-vars": "warn",
 		"typescript/no-non-null-assertion": "error",
 		"typescript/no-explicit-any": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"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,17 +45,18 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ast-grep/cli": "^0.44.1",
-		"@testing-library/jest-dom": "^6.9.1",
+		"@ast-grep/cli": "^0.45.0",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^7.0.0",
 		"@typescript/native": "npm:typescript@^7.0.2",
-		"jsdom": "^29.1.1",
-		"knip": "^6.27.0",
-		"oxfmt": "^0.59.0",
-		"oxlint": "^1.74.0",
+		"jsdom": "^30.0.1",
+		"knip": "^6.31.0",
+		"oxfmt": "^0.61.0",
+		"oxlint": "^1.76.0",
 		"typescript": "npm:@typescript/typescript6@^6.0.2",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=20"
+		"node": "^22.22.2 || ^24.15.0 || >=26.0.0"
 	}
 }