@ingram-tech/nk-blog 0.1.4 → 0.1.6

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` };
+}

package/src/render.tsx

@@ -0,0 +1,94 @@
+import { evaluate } from "@mdx-js/mdx";
+import type { ComponentType, ReactElement } from "react";
+import * as runtime from "react/jsx-runtime";
+import Markdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { PluggableList } from "unified";
+import type { BlogComponents } from "./contract.js";
+import { remarkLimitedMdx } from "./limited-mdx.js";
+import type { BlogPost } from "./types.js";
+
+export { remarkLimitedMdx, validateLimitedMdx } from "./limited-mdx.js";
+export type {
+	LimitedMdxOptions,
+	LimitedMdxResult,
+	LimitedMdxViolation,
+} from "./limited-mdx.js";
+
+/**
+ * The element map a site passes to style prose (h1–h4, p, code, tables, …).
+ * One key set shared by both pipelines — react-markdown's `Components` is the
+ * canonical shape. The map itself never ships from nk-blog: it is the brand.
+ */
+export type BlogElements = Components;
+
+// Per-post (Tier-2) components, merged over the site vocabulary in MDX scope.
+export type BespokeComponents = Record<string, ComponentType<never>>;
+
+/** Renders a `.md` body. Pure data — the automated publisher's format. */
+export const MarkdownBody: React.FC<{
+	content: string;
+	elements?: BlogElements;
+}> = ({ content, elements }) => (
+	<Markdown remarkPlugins={[remarkGfm]} components={elements}>
+		{content}
+	</Markdown>
+);
+
+/**
+ * Renders an `.mdx` body (async server component). `limited` (default true)
+ * enforces the vocabulary-only trust boundary; Tier-2 posts pass `bespoke`
+ * components, which turns enforcement off — those are human-reviewed code.
+ */
+export async function MdxBody(props: {
+	content: string;
+	components: BlogComponents;
+	elements?: BlogElements;
+	bespoke?: BespokeComponents;
+	limited?: boolean;
+}): Promise<ReactElement> {
+	// An *empty* bespoke map (a site conditionally spreading a possibly-empty
+	// registry) must not silently switch off the trust boundary — only actual
+	// human-reviewed components do.
+	const limited = props.limited ?? Object.keys(props.bespoke ?? {}).length === 0;
+	const scope = { ...props.components, ...props.bespoke };
+	const remarkPlugins: PluggableList = limited
+		? [remarkGfm, [remarkLimitedMdx, { allow: Object.keys(scope) }]]
+		: [remarkGfm];
+	const { default: MDXContent } = await evaluate(props.content, {
+		...runtime,
+		remarkPlugins,
+	});
+	return <MDXContent components={{ ...props.elements, ...scope }} />;
+}
+
+/** Format-dispatching renderer: the one component a post page needs. */
+export async function PostBody(props: {
+	post: BlogPost;
+	components: BlogComponents;
+	elements?: BlogElements;
+	bespoke?: BespokeComponents;
+}): Promise<ReactElement> {
+	if (props.post.format === "md") {
+		return <MarkdownBody content={props.post.content} elements={props.elements} />;
+	}
+	return MdxBody({
+		content: props.post.content,
+		components: props.components,
+		elements: props.elements,
+		bespoke: props.bespoke,
+	});
+}
+
+/**
+ * The hardened JSON-LD script tag, re-exported from nk-seo so it sits with the
+ * node builders that feed it (`blogPostArticle`, `blogPostBreadcrumbs`).
+ *
+ * nk-blog hands sites schema *nodes* and left rendering to them, which meant
+ * every site hand-rolled `<script type="application/ld+json"
+ * dangerouslySetInnerHTML={{ __html: JSON.stringify(nodes) }} />` — and a post
+ * title or FAQ answer containing `</script>` then closes the tag and injects
+ * markup into the page. `JsonLd` escapes `<`, so the safe path is now the one
+ * already in reach.
+ */
+export { JsonLd, serializeJsonLd } from "@ingram-tech/nk-seo/components";

package/src/rss.ts

@@ -0,0 +1,71 @@
+import type { BlogPostPreview } from "./types.js";
+
+export interface RssConfig {
+	title: string;
+	description?: string;
+	/** Absolute site origin, e.g. "https://example.com". */
+	siteUrl: string;
+	/** Path prefix of the blog, e.g. "/posts". */
+	basePath: string;
+	/** Absolute URL the feed is served from, e.g. `${siteUrl}/rss.xml`. */
+	feedUrl: string;
+	language?: string;
+}
+
+const escapeXml = (value: string): string =>
+	value
+		// XML 1.0 forbids most C0 controls even escaped — a stray \x08 pasted
+		// into a title would make strict parsers reject the whole feed.
+		// oxlint-disable-next-line no-control-regex -- stripping XML-invalid chars is the point
+		.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "")
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+
+/**
+ * RSS 2.0 feed for a post list. Serve from a route handler (`rss.xml/route.ts`
+ * with `export const dynamic = "force-static"`) so it renders at build.
+ */
+export function generateRss(config: RssConfig, posts: BlogPostPreview[]): string {
+	const items = posts
+		.map((post) => {
+			const url = `${config.siteUrl}${config.basePath}/${post.slug}`;
+			return [
+				"\t\t<item>",
+				`\t\t\t<title>${escapeXml(post.title)}</title>`,
+				`\t\t\t<link>${escapeXml(url)}</link>`,
+				`\t\t\t<guid isPermaLink="true">${escapeXml(url)}</guid>`,
+				`\t\t\t<pubDate>${new Date(post.date).toUTCString()}</pubDate>`,
+				`\t\t\t<description>${escapeXml(post.description)}</description>`,
+				...post.authors.map(
+					(author) => `\t\t\t<dc:creator>${escapeXml(author)}</dc:creator>`,
+				),
+				...(post.category
+					? [`\t\t\t<category>${escapeXml(post.category)}</category>`]
+					: []),
+				"\t\t</item>",
+			].join("\n");
+		})
+		.join("\n");
+
+	return [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">',
+		"\t<channel>",
+		`\t\t<title>${escapeXml(config.title)}</title>`,
+		`\t\t<link>${escapeXml(config.siteUrl + config.basePath)}</link>`,
+		`\t\t<description>${escapeXml(config.description ?? config.title)}</description>`,
+		`\t\t<language>${escapeXml(config.language ?? "en")}</language>`,
+		`\t\t<atom:link href="${escapeXml(config.feedUrl)}" rel="self" type="application/rss+xml"/>`,
+		...(posts[0]
+			? [
+					`\t\t<lastBuildDate>${new Date(posts[0].date).toUTCString()}</lastBuildDate>`,
+				]
+			: []),
+		items,
+		"\t</channel>",
+		"</rss>",
+		"",
+	].join("\n");
+}

package/src/schema.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+// YAML (via gray-matter) parses bare dates like `2026-04-30` into Date objects
+// and quoted ones into strings — accept both, emit ISO 8601.
+const isoDate = z.union([z.string(), z.date()]).transform((value, ctx) => {
+	const parsed = value instanceof Date ? value : new Date(value);
+	if (Number.isNaN(parsed.getTime())) {
+		ctx.addIssue({
+			code: "custom",
+			message: `Invalid date "${String(value)}". Use ISO format (YYYY-MM-DD).`,
+		});
+		return z.NEVER;
+	}
+	return parsed.toISOString();
+});
+
+const nonEmpty = z.string().trim().min(1);
+
+/**
+ * Slug shape shared by the frontmatter contract and the publisher: alnum runs
+ * separated by single `-`/`_`/`.`. Rules out everything that breaks routes,
+ * RSS/JSON-LD URLs, or — via the publisher's `${dir}/${slug}.md` commit path —
+ * traverses into arbitrary repo locations (`../.github/workflows/x`).
+ */
+export const slugPattern = /^[a-z0-9]+(?:[-._][a-z0-9]+)*$/;
+
+const slugSchema = z
+	.string()
+	.regex(
+		slugPattern,
+		"Slug must be lowercase alphanumerics separated by single '-', '_' or '.'",
+	);
+
+/**
+ * The shared frontmatter contract. Every post on every site validates against
+ * this; unknown keys are preserved-ignored (sites may carry extras locally).
+ *
+ * Normalizations: `coverImage` is accepted as an alias of `image`; `author`
+ * (string or list) and `authors` collapse into a single `authors: string[]`.
+ */
+export const blogFrontmatterSchema = z
+	.object({
+		title: nonEmpty,
+		seoTitle: nonEmpty.optional(),
+		description: nonEmpty,
+		date: isoDate,
+		updated: isoDate.optional(),
+		author: z.union([nonEmpty, z.array(nonEmpty)]).optional(),
+		authors: z.array(nonEmpty).optional(),
+		category: nonEmpty.optional(),
+		tags: z.array(nonEmpty).default([]),
+		image: nonEmpty.optional(),
+		coverImage: nonEmpty.optional(),
+		slug: slugSchema.optional(),
+		draft: z.boolean().default(false),
+		featured: z.boolean().default(false),
+		// Reserved fields — validated now so adding behavior later isn't breaking.
+		lang: nonEmpty.optional(),
+		canonical: nonEmpty.optional(),
+	})
+	.transform(({ author, authors, coverImage, image, ...rest }) => ({
+		...rest,
+		image: image ?? coverImage,
+		authors: authors ?? (Array.isArray(author) ? author : author ? [author] : []),
+	}));
+
+export type BlogFrontmatter = z.infer<typeof blogFrontmatterSchema>;
+export type BlogFrontmatterInput = z.input<typeof blogFrontmatterSchema>;

package/src/seo.ts

@@ -0,0 +1,69 @@
+import {
+	article,
+	type ArticleInput,
+	type ArticleNode,
+	breadcrumbList,
+	type BreadcrumbListNode,
+	type OrganizationInput,
+	type WithContext,
+} from "@ingram-tech/nk-seo";
+import type { BlogPostPreview } from "./types.js";
+
+export interface BlogSeoConfig {
+	/** Absolute site origin, e.g. "https://example.com". */
+	baseUrl: string;
+	/** Path prefix of the blog, e.g. "/posts" or "/blog". */
+	basePath: string;
+	/** Injected as the article publisher when provided. */
+	publisher?: OrganizationInput;
+	/** Crumb label for the blog index; defaults to "Blog". */
+	blogName?: string;
+}
+
+export function postUrl(post: BlogPostPreview, config: BlogSeoConfig): string {
+	return `${config.baseUrl}${config.basePath}/${post.slug}`;
+}
+
+// JSON-LD consumers don't resolve relative URLs, so anything without a scheme
+// (leading-`/` or bare `img/x.png`) is absolutized against the site. Unlike
+// nk-seo's `absoluteUrl`, an already-absolute value passes through untouched
+// rather than being origin-checked: a post's image can live on a CDN and its
+// `canonical` can be a cross-origin syndication override, both legitimately
+// off-origin — so this must not throw the way the canonical-link resolver does.
+const toAbsoluteUrl = (url: string, baseUrl: string): string =>
+	/^https?:\/\//.test(url)
+		? url
+		: `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+
+/** BlogPosting JSON-LD for a post — the nk-seo bridge. */
+export function blogPostArticle(
+	post: BlogPostPreview,
+	config: BlogSeoConfig,
+	overrides: Partial<ArticleInput> = {},
+): WithContext<ArticleNode> {
+	return article({
+		type: "BlogPosting",
+		headline: post.title,
+		description: post.description,
+		url: toAbsoluteUrl(post.canonical ?? postUrl(post, config), config.baseUrl),
+		datePublished: post.date,
+		dateModified: post.updated,
+		authors: post.authors.map((name) => ({ name })),
+		image: post.image ? toAbsoluteUrl(post.image, config.baseUrl) : undefined,
+		keywords: post.tags.length ? post.tags : undefined,
+		publisher: config.publisher,
+		...overrides,
+	});
+}
+
+/** Home → Blog → Post breadcrumb JSON-LD. */
+export function blogPostBreadcrumbs(
+	post: BlogPostPreview,
+	config: BlogSeoConfig,
+): WithContext<BreadcrumbListNode> {
+	return breadcrumbList([
+		{ name: "Home", url: config.baseUrl },
+		{ name: config.blogName ?? "Blog", url: `${config.baseUrl}${config.basePath}` },
+		{ name: post.title, url: postUrl(post, config) },
+	]);
+}

package/src/server.ts

@@ -0,0 +1,22 @@
+// Server entry: everything that touches the filesystem, the GitHub API, or
+// env. Import from pages/route handlers/scripts only — never from client
+// components (the root "." export carries the types you need there).
+export {
+	createBlog,
+	parsePost,
+	parsePostFileName,
+	type Blog,
+	type BlogConfig,
+	type BlogSource,
+	type RawPostFile,
+} from "./blog.js";
+export { fsSource } from "./sources/fs.js";
+export { githubSource, type GitHubRepoConfig } from "./sources/github.js";
+export {
+	publishPost,
+	serializePost,
+	type PublishedPost,
+	type PublishPostInput,
+} from "./sources/publish.js";
+export { generateRss, type RssConfig } from "./rss.js";
+export { keys } from "./keys.js";

package/src/sources/fs.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { BlogSource, RawPostFile } from "../blog.js";
+
+/**
+ * Build-time filesystem source. The blog contract is full SSG: call this from
+ * `generateStaticParams`-driven pages (with `dynamicParams = false`), sitemap
+ * and RSS route handlers — all of which run at build. It must NOT be relied on
+ * at request time on serverless hosts: output file tracing does not follow
+ * `fs` reads made inside a published package, so the content directory may be
+ * absent from the deployed function (`outputFileTracingIncludes` is the escape
+ * hatch if you truly need runtime reads).
+ */
+export function fsSource(dir: string): BlogSource {
+	const root = path.isAbsolute(dir) ? dir : path.join(process.cwd(), dir);
+
+	return {
+		async load(): Promise<RawPostFile[]> {
+			let entries;
+			try {
+				entries = await fs.readdir(root, { withFileTypes: true });
+			} catch (error) {
+				if (
+					error instanceof Error &&
+					"code" in error &&
+					error.code === "ENOENT"
+				) {
+					return [];
+				}
+				throw error;
+			}
+
+			const names: string[] = [];
+			for (const entry of entries) {
+				if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+					names.push(entry.name);
+				} else if (entry.isDirectory()) {
+					// Folder post: <slug>/index.md(x) with colocated assets/code.
+					for (const index of ["index.mdx", "index.md"]) {
+						try {
+							await fs.access(path.join(root, entry.name, index));
+							names.push(`${entry.name}/${index}`);
+							break;
+						} catch {
+							// keep looking
+						}
+					}
+				}
+			}
+
+			return Promise.all(
+				names.map(async (name) => ({
+					name,
+					content: await fs.readFile(path.join(root, name), "utf8"),
+				})),
+			);
+		},
+	};
+}