@ingram-tech/nk-blog 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-blog",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "File-based blog foundation for Next.js sites: frontmatter schema, build-time reader, limited-MDX rendering, a typed component contract with unstyled defaults, GitHub read/publish, and RSS.",
 	"license": "MIT",
 	"type": "module",
@@ -14,7 +14,10 @@
 	},
 	"sideEffects": false,
 	"files": [
-		"dist"
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx"
 	],
 	"exports": {
 		".": {
@@ -40,7 +43,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@ingram-tech/nk-seo": "^0.8.0",
+		"@ingram-tech/nk-seo": "^0.9.0",
 		"@mdx-js/mdx": "^3.1.1",
 		"gray-matter": "^4.0.3",
 		"react-markdown": "^10.1.0",
@@ -61,7 +64,7 @@
 		}
 	},
 	"devDependencies": {
-		"@ingram-tech/nk-dev": "0.11.1",
+		"@ingram-tech/nk-dev": "0.13.0",
 		"@types/mdast": "^4.0.4",
 		"@types/node": "^26.2.0",
 		"@types/react": "^19.2.18",

package/src/blog.ts

@@ -0,0 +1,170 @@
+import matter from "gray-matter";
+import { blogFrontmatterSchema } from "./schema.js";
+import { DEFAULT_WORDS_PER_MINUTE, readingTime } from "./reading-time.js";
+import type { BlogPost, BlogPostPreview, PostFormat } from "./types.js";
+
+/** A content file, named relative to the content dir ("slug.md", "slug/index.mdx"). */
+export interface RawPostFile {
+	name: string;
+	content: string;
+}
+
+export interface BlogSource {
+	load(): Promise<RawPostFile[]>;
+}
+
+export interface BlogConfig {
+	source: BlogSource;
+	/** Byline when a post declares none (each site sets its own). */
+	defaultAuthor?: string;
+	defaultCategory?: string;
+	wordsPerMinute?: number;
+	/** Include drafts (listing pages typically pass `NODE_ENV !== "production"`). */
+	drafts?: boolean;
+	/**
+	 * Site-specific image fallback (e.g. "look in /public/images/posts/<slug>").
+	 * This is config precisely so per-site divergence never forks the reader.
+	 */
+	resolveImage?: (post: { slug: string; image?: string }) => string | undefined;
+	/**
+	 * "throw" (default) fails the build on malformed frontmatter — a real post
+	 * silently missing from a site is worse than a red build. Remote sources
+	 * (admin listing over GitHub) prefer "skip" to keep one bad file from
+	 * hiding a whole target.
+	 */
+	onInvalid?: "throw" | "skip";
+}
+
+export interface Blog {
+	/** All non-draft posts, newest first, with bodies. */
+	posts(): Promise<BlogPost[]>;
+	/** All non-draft posts, newest first, without bodies. */
+	previews(): Promise<BlogPostPreview[]>;
+	post(slug: string): Promise<BlogPost | null>;
+	slugs(): Promise<string[]>;
+	/** The pinned (`featured: true`) post, else the newest. */
+	featured(): Promise<BlogPost | null>;
+}
+
+const POST_FILE = /^(?:(?<flat>[^/]+)|(?<dir>[^/]+)\/index)\.(?<ext>mdx?)$/;
+
+interface ParsedName {
+	slug: string;
+	format: PostFormat;
+	draftByName: boolean;
+}
+
+/** "slug.md", "slug.mdx", "slug/index.md(x)" → slug + format; else null. */
+export function parsePostFileName(name: string): ParsedName | null {
+	const match = POST_FILE.exec(name);
+	const groups = match?.groups;
+	if (!groups) return null;
+	const base = groups.flat ?? groups.dir;
+	if (!base) return null;
+	return {
+		slug: base.replace(/^_/, ""),
+		format: groups.ext === "mdx" ? "mdx" : "md",
+		// Legacy `_draft.md` convention, honored as an alias of `draft: true`.
+		draftByName: base.startsWith("_"),
+	};
+}
+
+export function parsePost(file: RawPostFile, config: BlogConfig): BlogPost | null {
+	const named = parsePostFileName(file.name);
+	if (!named) return null;
+
+	const { data, content } = matter(file.content);
+	const result = blogFrontmatterSchema.safeParse(data);
+	if (!result.success) {
+		if ((config.onInvalid ?? "throw") === "skip") {
+			console.warn(
+				`nk-blog: skipping ${file.name}: ${result.error.issues
+					.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+					.join("; ")}`,
+			);
+			return null;
+		}
+		throw new Error(
+			`nk-blog: invalid frontmatter in ${file.name}: ${result.error.issues
+				.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+				.join("; ")}`,
+		);
+	}
+
+	const frontmatter = result.data;
+	const slug = frontmatter.slug ?? named.slug;
+	const body = content.trim();
+	const authors = frontmatter.authors.length
+		? frontmatter.authors
+		: config.defaultAuthor
+			? [config.defaultAuthor]
+			: [];
+	const time = readingTime(body, config.wordsPerMinute ?? DEFAULT_WORDS_PER_MINUTE);
+	const image =
+		config.resolveImage?.({ slug, image: frontmatter.image }) ?? frontmatter.image;
+
+	return {
+		slug,
+		title: frontmatter.title,
+		seoTitle: frontmatter.seoTitle,
+		description: frontmatter.description,
+		date: frontmatter.date,
+		updated: frontmatter.updated,
+		authors,
+		author: authors[0] ?? "",
+		category: frontmatter.category ?? config.defaultCategory,
+		tags: frontmatter.tags,
+		image,
+		draft: frontmatter.draft || named.draftByName,
+		featured: frontmatter.featured,
+		lang: frontmatter.lang,
+		canonical: frontmatter.canonical,
+		format: named.format,
+		readingTimeMinutes: time.minutes,
+		readTime: time.text,
+		content: body,
+	};
+}
+
+export function createBlog(config: BlogConfig): Blog {
+	const posts = async (): Promise<BlogPost[]> => {
+		const files = await config.source.load();
+		const parsed = files
+			.map((file) => parsePost(file, config))
+			.filter((post): post is BlogPost => post !== null);
+
+		// Collision check BEFORE the draft filter: a draft colliding with a live
+		// post must fail the production build too, not only draft-enabled
+		// previews. Two files resolving to one slug is a routing conflict —
+		// always a loud build failure, never a quiet last-one-wins.
+		const seen = new Map<string, BlogPost>();
+		for (const post of parsed) {
+			if (seen.has(post.slug)) {
+				throw new Error(`nk-blog: duplicate slug "${post.slug}"`);
+			}
+			seen.set(post.slug, post);
+		}
+
+		return [...seen.values()]
+			.filter((post) => config.drafts === true || !post.draft)
+			.sort(
+				(a, b) =>
+					new Date(b.date).getTime() - new Date(a.date).getTime() ||
+					// Same-day posts: deterministic order between builds.
+					a.slug.localeCompare(b.slug),
+			);
+	};
+
+	return {
+		posts,
+		previews: async () =>
+			(await posts()).map(({ content: _content, ...preview }) => preview),
+		post: async (slug) =>
+			(await posts()).find((candidate) => candidate.slug === slug) ?? null,
+		slugs: async () => (await posts()).map((post) => post.slug),
+		featured: async () => {
+			const all = await posts();
+			return all.find((post) => post.featured) ?? all[0] ?? null;
+		},
+	};
+}

package/src/contract.ts

@@ -0,0 +1,97 @@
+import type { ComponentType, ReactNode } from "react";
+import { z } from "zod";
+
+/**
+ * The vocabulary manifest — the cross-site component contract.
+ *
+ * A Tier-1 post may reference exactly these components by bare name. The
+ * package owns the names and prop schemas; each site owns the pixels (see
+ * `@ingram-tech/nk-blog/unstyled` for the behavior-correct defaults). The
+ * admin publisher validates a post against this manifest (at the version the
+ * target site pins) before committing it.
+ */
+export const VOCABULARY = [
+	"Callout",
+	"Figure",
+	"YouTube",
+	"Tweet",
+	"NewsletterSubscribe",
+] as const;
+
+export type VocabularyName = (typeof VOCABULARY)[number];
+
+// MDX literal attributes arrive as strings (`width="1200"`), so dimension-ish
+// props coerce rather than demand numbers.
+const dimension = z.union([z.number(), z.string().regex(/^\d+$/)]);
+
+export const calloutProps = z.object({
+	variant: z.enum(["note", "tip", "warning", "important"]).default("note"),
+	title: z.string().optional(),
+});
+
+export const figureProps = z.object({
+	src: z.string().min(1),
+	alt: z.string(),
+	caption: z.string().optional(),
+	width: dimension.optional(),
+	height: dimension.optional(),
+});
+
+export const youTubeProps = z.object({
+	id: z.string().min(1),
+	title: z.string().optional(),
+	start: dimension.optional(),
+});
+
+export const tweetProps = z.object({
+	id: z.string().min(1),
+});
+
+export const newsletterSubscribeProps = z.object({
+	action: z.string().min(1),
+	placeholder: z.string().optional(),
+	buttonLabel: z.string().optional(),
+});
+
+/** Machine-checkable side of the contract, keyed by component name. */
+export const vocabularyProps = {
+	Callout: calloutProps,
+	Figure: figureProps,
+	YouTube: youTubeProps,
+	Tweet: tweetProps,
+	NewsletterSubscribe: newsletterSubscribeProps,
+} satisfies Record<VocabularyName, z.ZodType>;
+
+// React-facing prop types: the schema's input shape plus children/className,
+// which Zod does not model.
+type WithReactExtras<T> = T & { children?: ReactNode; className?: string };
+
+export type CalloutProps = WithReactExtras<z.input<typeof calloutProps>>;
+export type FigureProps = WithReactExtras<z.input<typeof figureProps>>;
+export type YouTubeProps = WithReactExtras<z.input<typeof youTubeProps>>;
+export type TweetProps = WithReactExtras<z.input<typeof tweetProps>>;
+export type NewsletterSubscribeProps = WithReactExtras<
+	z.input<typeof newsletterSubscribeProps>
+>;
+
+export interface VocabularyPropsMap {
+	Callout: CalloutProps;
+	Figure: FigureProps;
+	YouTube: YouTubeProps;
+	Tweet: TweetProps;
+	NewsletterSubscribe: NewsletterSubscribeProps;
+}
+
+/**
+ * The exhaustive registry a site must provide. Exhaustiveness is the point:
+ * a site missing a vocabulary component fails `tsc`, so an admin-published
+ * post can never reference something a site cannot render.
+ */
+export type BlogComponents = {
+	[K in VocabularyName]: ComponentType<VocabularyPropsMap[K]>;
+};
+
+/** Identity helper — exists purely for inference and error locality. */
+export function defineBlogComponents(components: BlogComponents): BlogComponents {
+	return components;
+}

package/src/date.ts

@@ -0,0 +1,22 @@
+/**
+ * The one post-date formatter (one site shipped two of these). Defaults to the
+ * long-form English style every site currently renders: "April 30, 2026".
+ *
+ * Formats in UTC by default: post dates are normalized to UTC midnight, so a
+ * local-zone format would render the previous day anywhere west of UTC (and
+ * hydration-mismatch per viewer when used client-side). Pass `timeZone` in
+ * `options` to override.
+ */
+export function formatPostDate(
+	isoDate: string,
+	locale = "en",
+	options: Intl.DateTimeFormatOptions = {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+	},
+): string {
+	return new Intl.DateTimeFormat(locale, { timeZone: "UTC", ...options }).format(
+		new Date(isoDate),
+	);
+}

package/src/http.ts

@@ -0,0 +1,16 @@
+export function toErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export async function assertResponseOk(
+	response: Response,
+	message: string,
+): Promise<void> {
+	if (response.ok) return;
+	const body = await response.text().catch(() => "");
+	throw new Error(
+		`${message}: ${response.status} ${response.statusText}${
+			body ? ` — ${body.slice(0, 300)}` : ""
+		}`,
+	);
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// Root entry: the contract — schema, types, vocabulary manifest — plus pure
+// helpers. Importable anywhere (client, admin, route handlers); no fs, no
+// components, no MDX compiler. The reader/sources live at "./server", the
+// renderers at "./render", the default components at "./unstyled".
+export {
+	blogFrontmatterSchema,
+	type BlogFrontmatter,
+	type BlogFrontmatterInput,
+} from "./schema.js";
+export type { BlogPost, BlogPostPreview, PostFormat } from "./types.js";
+export {
+	VOCABULARY,
+	vocabularyProps,
+	defineBlogComponents,
+	calloutProps,
+	figureProps,
+	youTubeProps,
+	tweetProps,
+	newsletterSubscribeProps,
+	type BlogComponents,
+	type VocabularyName,
+	type VocabularyPropsMap,
+	type CalloutProps,
+	type FigureProps,
+	type YouTubeProps,
+	type TweetProps,
+	type NewsletterSubscribeProps,
+} from "./contract.js";
+export {
+	readingTime,
+	DEFAULT_WORDS_PER_MINUTE,
+	type ReadingTime,
+} from "./reading-time.js";
+export { formatPostDate } from "./date.js";
+export {
+	blogPostArticle,
+	blogPostBreadcrumbs,
+	postUrl,
+	type BlogSeoConfig,
+} from "./seo.js";

package/src/keys.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+/**
+ * Env contract. Only the GitHub source/publisher needs anything, and callers
+ * may inject the token directly instead — so everything here is optional.
+ */
+export const keys = () =>
+	z
+		.object({
+			GITHUB_TOKEN: z.string().min(1).optional(),
+		})
+		.parse(process.env);

package/src/limited-mdx.ts

@@ -0,0 +1,267 @@
+import matter from "gray-matter";
+import type { Root } from "mdast";
+import type { MdxJsxFlowElement, MdxJsxTextElement } from "mdast-util-mdx-jsx";
+import { visit } from "unist-util-visit";
+import type { VFile } from "vfile";
+import { toErrorMessage } from "./http.js";
+
+/**
+ * The "limited MDX" trust boundary, enforced in the AST — not a convention.
+ *
+ * MDX is a programming language: `{process.env.X}`, `export const x = …`, and
+ * ESM imports all execute server-side with zero components involved. A Tier-1
+ * post (the only thing the automated publisher may emit as .mdx) is therefore
+ * restricted to prose + whitelisted JSX elements with literal attributes;
+ * every expression/ESM construct is rejected at compile time.
+ */
+export interface LimitedMdxOptions {
+	/** Component names the post may reference (the site's vocabulary). */
+	allow: readonly string[];
+}
+
+// Lowercase JSX that isn't one of these is almost certainly a miscased
+// vocabulary reference (<callout>), which MDX would render as an inert,
+// invisible HTML element — the one silent failure mode, so reject it.
+const HTML_TAGS = new Set([
+	"a",
+	"abbr",
+	"aside",
+	"b",
+	"blockquote",
+	"br",
+	"caption",
+	"cite",
+	"code",
+	"dd",
+	"del",
+	"details",
+	"div",
+	"dl",
+	"dt",
+	"em",
+	"figcaption",
+	"figure",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"hr",
+	"i",
+	"img",
+	"ins",
+	"kbd",
+	"li",
+	"main",
+	"mark",
+	"nav",
+	"ol",
+	"p",
+	"pre",
+	"q",
+	"s",
+	"samp",
+	"section",
+	"small",
+	"span",
+	"strong",
+	"sub",
+	"summary",
+	"sup",
+	"table",
+	"tbody",
+	"td",
+	"tfoot",
+	"th",
+	"thead",
+	"tr",
+	"u",
+	"ul",
+	"var",
+	"video",
+	"wbr",
+]);
+
+type JsxElement = MdxJsxFlowElement | MdxJsxTextElement;
+
+// Attributes that carry a URL the browser will navigate/load — the XSS surface
+// of otherwise-inert HTML (`<a href="javascript:…">`).
+const URL_ATTRIBUTES = new Set([
+	"href",
+	"src",
+	"poster",
+	"cite",
+	"action",
+	"formaction",
+	"data",
+]);
+
+/**
+ * Accept relative paths/anchors and http(s)/mailto/tel absolute URLs; reject
+ * every other scheme (`javascript:`, `data:`, `vbscript:`, …). Control chars
+ * and whitespace are stripped before scheme detection because browsers strip
+ * them when parsing, so `java\tscript:` would otherwise sneak through.
+ */
+function isSafeUrl(raw: string): boolean {
+	// oxlint-disable-next-line no-control-regex -- stripping what browsers strip is the point
+	const cleaned = raw.replace(/[\u0000-\u0020]/g, "");
+	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(cleaned);
+	if (!scheme) return true;
+	return /^(?:https?|mailto|tel)$/i.test(scheme[1] ?? "");
+}
+
+function checkElement(node: JsxElement, allow: readonly string[], file: VFile): void {
+	const name = node.name;
+	// Nameless = fragment (<>…</>), which is inert prose grouping.
+	if (name === null) return;
+
+	if (/^[a-z]/.test(name)) {
+		if (!HTML_TAGS.has(name)) {
+			file.fail(
+				`Unknown HTML tag <${name}> — a miscased component? Vocabulary names are capitalized.`,
+				node,
+			);
+		}
+	} else if (!allow.includes(name)) {
+		file.fail(
+			`<${name}> is not in this blog's component vocabulary (${allow.join(", ")}).`,
+			node,
+		);
+	}
+
+	for (const attribute of node.attributes) {
+		if (attribute.type !== "mdxJsxAttribute") {
+			file.fail(
+				`<${name}> uses a spread attribute; only literal props are allowed.`,
+				node,
+			);
+			continue;
+		}
+		const value = attribute.value;
+		// null/undefined = bare boolean prop; string = literal. Anything else is
+		// an attribute-value expression — executable, so allow only simple
+		// literals.
+		if (value === null || value === undefined || typeof value === "string") {
+			if (
+				typeof value === "string" &&
+				URL_ATTRIBUTES.has(attribute.name.toLowerCase()) &&
+				!isSafeUrl(value)
+			) {
+				file.fail(
+					`<${name} ${attribute.name}="…"> uses a URL scheme that is not allowed in limited MDX (http/https/mailto/tel or a relative path).`,
+					node,
+				);
+			}
+			continue;
+		}
+		const statement = value.data?.estree?.body[0];
+		const expression =
+			statement?.type === "ExpressionStatement"
+				? statement.expression
+				: undefined;
+		if (expression?.type !== "Literal") {
+			file.fail(
+				`<${name} ${attribute.name}={…}> — attribute expressions are not allowed in limited MDX; use a literal.`,
+				node,
+			);
+			continue;
+		}
+		// A braced string literal is still a URL the browser will navigate
+		// (`href={"javascript:…"}`), so it must clear the same scheme guard as the
+		// plain-string branch above — the `Literal` check alone would wave it through.
+		if (
+			typeof expression.value === "string" &&
+			URL_ATTRIBUTES.has(attribute.name.toLowerCase()) &&
+			!isSafeUrl(expression.value)
+		) {
+			file.fail(
+				`<${name} ${attribute.name}={…}> uses a URL scheme that is not allowed in limited MDX (http/https/mailto/tel or a relative path).`,
+				node,
+			);
+		}
+	}
+}
+
+/** Remark plugin implementing the boundary. Throws (via `file.fail`) on violation. */
+export function remarkLimitedMdx(options: LimitedMdxOptions) {
+	return (tree: Root, file: VFile): void => {
+		visit(tree, (node) => {
+			switch (node.type) {
+				case "mdxjsEsm":
+					file.fail(
+						"import/export statements are not allowed in limited MDX.",
+						node,
+					);
+					break;
+				case "mdxFlowExpression":
+				case "mdxTextExpression":
+					file.fail("{…} expressions are not allowed in limited MDX.", node);
+					break;
+				case "mdxJsxFlowElement":
+				case "mdxJsxTextElement":
+					checkElement(node, options.allow, file);
+					break;
+				// Plain markdown links/images compile to real anchors too — unlike
+				// react-markdown (which sanitizes by default), the MDX pipeline
+				// applies no urlTransform, so `[x](javascript:…)` must die here.
+				case "link":
+				case "image":
+				case "definition":
+					if (!isSafeUrl(node.url)) {
+						file.fail(
+							`Link/image URL "${node.url}" uses a scheme that is not allowed in limited MDX.`,
+							node,
+						);
+					}
+					break;
+				default:
+					break;
+			}
+		});
+	};
+}
+
+export interface LimitedMdxViolation {
+	message: string;
+	line?: number;
+	column?: number;
+}
+
+export interface LimitedMdxResult {
+	ok: boolean;
+	errors: LimitedMdxViolation[];
+}
+
+/**
+ * Admin's pre-publish lint: compile (without evaluating) a post source —
+ * frontmatter included — against a vocabulary. Also surfaces MDX syntax
+ * errors, so an LLM-authored post can never break a target site's build.
+ */
+export async function validateLimitedMdx(
+	source: string,
+	options: LimitedMdxOptions,
+): Promise<LimitedMdxResult> {
+	const { compile } = await import("@mdx-js/mdx");
+	const { default: remarkGfm } = await import("remark-gfm");
+	const { content } = matter(source);
+	try {
+		await compile(content, {
+			remarkPlugins: [remarkGfm, [remarkLimitedMdx, options]],
+		});
+		return { ok: true, errors: [] };
+	} catch (error) {
+		const place =
+			error !== null &&
+			typeof error === "object" &&
+			"line" in error &&
+			"column" in error
+				? {
+						line: typeof error.line === "number" ? error.line : undefined,
+						column:
+							typeof error.column === "number" ? error.column : undefined,
+					}
+				: {};
+		return { ok: false, errors: [{ message: toErrorMessage(error), ...place }] };
+	}
+}

package/src/reading-time.ts

@@ -0,0 +1,21 @@
+export const DEFAULT_WORDS_PER_MINUTE = 220;
+
+export interface ReadingTime {
+	words: number;
+	minutes: number;
+	/** e.g. "5 min read". */
+	text: string;
+}
+
+/** Real reading time from the body — replaces the fleet's faked "5 min read". */
+export function readingTime(
+	content: string,
+	wordsPerMinute: number = DEFAULT_WORDS_PER_MINUTE,
+): ReadingTime {
+	const words = content
+		.trim()
+		.split(/\s+/)
+		.filter((token) => token.length > 0).length;
+	const minutes = Math.max(1, Math.ceil(words / wordsPerMinute));
+	return { words, minutes, text: `${minutes} min read` };
+}