@haruhimemoe/next-kit 0.4.0 → 0.6.0

package/dist/api-keys/store.js

@@ -0,0 +1,95 @@
+/**
+ * @file src/api-keys/store.ts
+ * @desc One API key per user in MongoDB (collection api_keys): issue (replaces), info, revoke,
+ *       authenticate and account deletion. Only the SHA-256 hash and a display prefix are
+ *       stored. Two issues racing still leave one key (unique userId; the loser updates).
+ *       authenticate gives the owner's user id; who that user is stays the app's call.
+ *       lastUsedAt is written at most once an hour. Moved from packs (src/services/api-keys.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { ObjectId } from "mongodb";
+import { isDuplicateKeyError } from "../mongo/duplicate.js";
+import { ensureIndexes as buildIndexes } from "../mongo/indexes.js";
+import { apiKeyDisplay, assertApiKeyPrefix, generateApiKey, hashApiKey, isApiKeyFormat, } from "./format.js";
+/** The collection every app keeps its keys in. */
+export const API_KEYS_COLLECTION = "api_keys";
+/** lastUsedAt is written at most this often, to save writes. */
+export const LAST_USED_INTERVAL_MS = 60 * 60 * 1000;
+const toInfo = (doc) => ({
+    prefix: doc.prefix,
+    createdAt: doc.createdAt.toISOString(),
+    lastUsedAt: doc.lastUsedAt ? doc.lastUsedAt.toISOString() : null,
+});
+/**
+ * @function apiKeyIndexSpecs
+ * @param collection {string} the keys collection (default api_keys)
+ * @returns {IndexSpec[]} unique userId and unique hash, for the app's own index list
+ */
+export const apiKeyIndexSpecs = (collection = API_KEYS_COLLECTION) => [
+    { collection, key: { userId: 1 }, unique: true },
+    // The hash is a credential digest: never log its values.
+    { collection, key: { hash: 1 }, unique: true, secret: true },
+];
+/**
+ * @function createApiKeyStore
+ * @param options {ApiKeyStoreOptions} the app prefix, the database, the collection (default
+ *        api_keys) and a clock (default Date.now)
+ * @returns {ApiKeyStore} the key operations for that app
+ * @throws {TypeError} on a bad prefix
+ */
+export const createApiKeyStore = ({ prefix, db, collection = API_KEYS_COLLECTION, 
+// Read per call, so fake timers in app tests move it.
+now = () => Date.now(), }) => {
+    assertApiKeyPrefix(prefix);
+    const keys = async () => (await db()).collection(collection);
+    const issue = async (userId) => {
+        const key = generateApiKey(prefix);
+        const filter = { userId: new ObjectId(userId) };
+        const update = {
+            $set: { prefix: apiKeyDisplay(key), hash: hashApiKey(key), createdAt: new Date(now()) },
+            $unset: { lastUsedAt: 1 },
+        };
+        const upsert = async () => (await keys()).findOneAndUpdate(filter, update, { upsert: true, returnDocument: "after" });
+        const doc = await upsert().catch((error) => {
+            if (!isDuplicateKeyError(error))
+                throw error;
+            return upsert();
+        });
+        if (!doc)
+            throw new Error("api key upsert returned no document");
+        return { key, apiKey: toInfo(doc) };
+    };
+    const authenticate = async (key) => {
+        if (!isApiKeyFormat(prefix, key))
+            return null;
+        const hash = hashApiKey(key);
+        const collectionRef = await keys();
+        const doc = await collectionRef.findOne({ hash });
+        if (!doc)
+            return null;
+        const stamp = async () => {
+            const at = now();
+            if (doc.lastUsedAt && at - doc.lastUsedAt.getTime() < LAST_USED_INTERVAL_MS)
+                return;
+            // Filter on the hash too, so a regenerate in between isn't stamped with this use.
+            await collectionRef.updateOne({ _id: doc._id, hash }, { $set: { lastUsedAt: new Date(at) } });
+        };
+        return { userId: doc.userId.toString(), stamp };
+    };
+    return {
+        prefix,
+        issue,
+        authenticate,
+        info: async (userId) => {
+            const doc = await (await keys()).findOne({ userId: new ObjectId(userId) });
+            return doc ? toInfo(doc) : null;
+        },
+        revoke: async (userId) => (await (await keys()).deleteOne({ userId: new ObjectId(userId) })).deletedCount === 1,
+        deleteFor: async (userId) => (await (await keys()).deleteMany({ userId: new ObjectId(userId) })).deletedCount,
+        ensureIndexes: async () => {
+            await buildIndexes(await db(), apiKeyIndexSpecs(collection));
+        },
+    };
+};

package/dist/check/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @file src/check/cli.ts
+ * @desc `next-kit check [dir]`: lists src/app and content (when it exists) under dir (default:
+ *       the working directory), runs checkStandards and prints one line per standard. Exits 1
+ *       when one fails or src/app is missing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
+ */
+/**
+ * @function runCheck
+ * @param root {string} the app's root (holds src/app and, optionally, content/)
+ * @param log {(line: string) => void} where lines go (default console.log)
+ * @returns {number} 0 when every standard passes, otherwise 1
+ */
+export declare const runCheck: (root: string, log?: (line: string) => void) => number;

package/dist/check/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * @file src/check/cli.ts
+ * @desc `next-kit check [dir]`: lists src/app and content (when it exists) under dir (default:
+ *       the working directory), runs checkStandards and prints one line per standard. Exits 1
+ *       when one fails or src/app is missing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { pathToFileURL } from "node:url";
+import { checkStandards } from "./standards.js";
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)]);
+const relativeFiles = (dir) => walk(dir).map((file) => relative(dir, file).split(sep).join("/"));
+/**
+ * @function runCheck
+ * @param root {string} the app's root (holds src/app and, optionally, content/)
+ * @param log {(line: string) => void} where lines go (default console.log)
+ * @returns {number} 0 when every standard passes, otherwise 1
+ */
+export const runCheck = (root, log = console.log) => {
+    const app = join(root, "src", "app");
+    if (!existsSync(app)) {
+        log(`next-kit check: no src/app in ${root}`);
+        return 1;
+    }
+    const contentDir = join(root, "content");
+    const contentFiles = existsSync(contentDir) ? relativeFiles(contentDir) : [];
+    const results = checkStandards(relativeFiles(app), contentFiles);
+    for (const result of results) {
+        log(`${result.ok ? "pass" : "FAIL"}  ${result.label}`);
+        for (const missing of result.missing)
+            log(`      missing ${missing}`);
+    }
+    return results.every((result) => result.ok) ? 0 : 1;
+};
+/* v8 ignore start */
+/** True when this file is the one Node was asked to run, even through a symlinked bin: a
+ * symlinked `next-kit` resolves argv[1] to the link, while import.meta.url is the realpath. */
+const isMainEntry = () => {
+    const entry = argv[1];
+    if (!entry || !existsSync(entry))
+        return false;
+    return pathToFileURL(realpathSync(entry)).href === import.meta.url;
+};
+if (isMainEntry()) {
+    const [command, dir] = argv.slice(2);
+    if (command !== "check") {
+        console.log("usage: next-kit check [dir]");
+        exit(2);
+    }
+    exit(runCheck(dir ?? cwd()));
+}
+/* v8 ignore stop */

package/dist/check/standards.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/check/standards.ts
+ * @desc The routes and content files every haruhime app serves, checked against an app's route
+ *       file list (paths under src/app) and content file list (paths under content/). Crawl and
+ *       brand are always checked; legal always checks its three routes plus its two content
+ *       files; docs joins in once api/v1 exists or a content/docs file does; guides joins in
+ *       only once a content/guides file does; the API standard, once api/v1 exists, checks its
+ *       three routes plus content/docs/api.mdx. Checks files only: the content registry itself
+ *       is never parsed.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
+ */
+/** One standard's outcome. `missing` entries carry their own prefix (src/app/... or content/...). */
+export type StandardResult = {
+    id: string;
+    label: string;
+    ok: boolean;
+    missing: string[];
+};
+/**
+ * @function checkStandards
+ * @param appFiles {readonly string[]} every file under src/app, relative, "/"-separated
+ * @param contentFiles {readonly string[]} every file under content/, relative, "/"-separated
+ * @returns {StandardResult[]} crawl and brand always, legal always, docs once api/v1 exists or
+ *   a content/docs file does, guides once a content/guides file does, and the API standard once
+ *   api/v1 exists
+ */
+export declare const checkStandards: (appFiles: readonly string[], contentFiles?: readonly string[]) => StandardResult[];

package/dist/check/standards.js

@@ -0,0 +1,85 @@
+/**
+ * @file src/check/standards.ts
+ * @desc The routes and content files every haruhime app serves, checked against an app's route
+ *       file list (paths under src/app) and content file list (paths under content/). Crawl and
+ *       brand are always checked; legal always checks its three routes plus its two content
+ *       files; docs joins in once api/v1 exists or a content/docs file does; guides joins in
+ *       only once a content/guides file does; the API standard, once api/v1 exists, checks its
+ *       three routes plus content/docs/api.mdx. Checks files only: the content registry itself
+ *       is never parsed.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
+ */
+/** A route under src/app, matched against any of `patterns`. */
+const route = (name, ...patterns) => ({
+    missing: `src/app/${name}`,
+    matches: (app) => app.some((file) => patterns.some((pattern) => pattern.test(file))),
+});
+/** A file under content/, matched by exact path. */
+const content = (path) => ({
+    missing: `content/${path}`,
+    matches: (_app, files) => files.includes(path),
+});
+const CRAWL = [
+    route("robots.ts", /^robots\.(ts|js)$/, /^robots\.txt\/route\.(ts|js)$/),
+    route("sitemap.ts", /^sitemap\.(ts|js)$/, /^sitemap\.xml\/route\.(ts|js)$/),
+    route("llms.txt/route.ts", /^llms\.txt\/route\.(ts|js)$/),
+    route("llms-full.txt/route.ts", /^llms-full\.txt\/route\.(ts|js)$/),
+    route(".well-known/security.txt/route.ts", /^\.well-known\/security\.txt\/route\.(ts|js)$/),
+];
+const BRAND = [route("brand/page.tsx", /^brand\/page\.(tsx|jsx|ts|js)$/)];
+/** docs/page.tsx, docs/[x]/page.tsx and docs/[x]/md/route.ts under a section, any segment name. */
+const sectionRoutes = (section) => [
+    route(`${section}/page.tsx`, new RegExp(`^${section}/page\\.(tsx|jsx|ts|js)$`)),
+    route(`${section}/[x]/page.tsx`, new RegExp(`^${section}/\\[[^\\]]+\\]/page\\.(tsx|jsx|ts|js)$`)),
+    route(`${section}/[x]/md/route.ts`, new RegExp(`^${section}/\\[[^\\]]+\\]/md/route\\.(ts|js)$`)),
+];
+const LEGAL = [
+    ...sectionRoutes("legal"),
+    content("legal/terms.mdx"),
+    content("legal/privacy.mdx"),
+];
+const DOCS = sectionRoutes("docs");
+const GUIDES = sectionRoutes("guides");
+const API = [
+    route("api/v1/me/route.ts", /^api\/v1\/me\/route\.(ts|js)$/),
+    route("api/v1/openapi.json/route.ts", /^api\/v1\/openapi\.json\/route\.(ts|js)$/),
+    route("api/me/api-key/route.ts", /^api\/me\/api-key\/route\.(ts|js)$/),
+    content("docs/api.mdx"),
+];
+const evaluate = (id, label, reqs, app, files) => {
+    const missing = reqs.filter((req) => !req.matches(app, files)).map((req) => req.missing);
+    return { id, label, ok: missing.length === 0, missing };
+};
+/** Route groups like (public)/ don't change the URL, so they are dropped before matching. */
+const ungrouped = (file) => file.replace(/(^|\/)\([^)]+\)(?=\/)/g, "").replace(/^\//, "");
+/**
+ * @function checkStandards
+ * @param appFiles {readonly string[]} every file under src/app, relative, "/"-separated
+ * @param contentFiles {readonly string[]} every file under content/, relative, "/"-separated
+ * @returns {StandardResult[]} crawl and brand always, legal always, docs once api/v1 exists or
+ *   a content/docs file does, guides once a content/guides file does, and the API standard once
+ *   api/v1 exists
+ */
+export const checkStandards = (appFiles, contentFiles = []) => {
+    const app = appFiles.map(ungrouped);
+    const hasApi = app.some((file) => file.startsWith("api/v1/"));
+    const hasDocsContent = contentFiles.some((file) => file.startsWith("docs/"));
+    const hasGuidesContent = contentFiles.some((file) => file.startsWith("guides/"));
+    const results = [
+        evaluate("crawl", "Crawl files", CRAWL, app, contentFiles),
+        evaluate("brand", "Brand page", BRAND, app, contentFiles),
+        evaluate("legal", "Legal pages", LEGAL, app, contentFiles),
+    ];
+    if (hasApi || hasDocsContent) {
+        results.push(evaluate("docs", "Docs pages", DOCS, app, contentFiles));
+    }
+    if (hasGuidesContent) {
+        results.push(evaluate("guides", "Guides pages", GUIDES, app, contentFiles));
+    }
+    if (hasApi) {
+        results.push(evaluate("api", "Public API", API, app, contentFiles));
+    }
+    return results;
+};

package/dist/docs/crawl.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file src/docs/crawl.ts
+ * @desc /llms.txt, /llms-full.txt, sitemap entries and the ".md" mirror rewrite, built straight
+ *       from a content registry. Pure: no node: imports or file reads here (an app's
+ *       `read`/`readContentMarkdown` provides the Markdown), so it runs anywhere `docs` does.
+ *       Reuses `llmsTxt`/`llmsFull` from `../seo/llms.js` for formatting, so escaping and section
+ *       shape stay the same as every other haruhime.moe crawl file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type LlmsFullPart } from "../seo/llms.js";
+import { type Site } from "../seo/site.js";
+import type { SitemapRecord } from "../seo/sitemap.js";
+import { type Content, type ContentSection } from "./registry.js";
+/** The "API" section's links: a title, an already-absolute URL and an optional note. */
+export type ContentApiLink = {
+    title: string;
+    url: string;
+    note?: string;
+};
+/** contentLlmsTxt's options. */
+export type ContentLlmsTxtOptions = {
+    site: Site;
+    title: string;
+    summary: string;
+    notes?: readonly string[];
+    content: Content;
+    /** The "API" section's links, like the OpenAPI document or `/api/v1/me`. */
+    api?: readonly ContentApiLink[];
+};
+/**
+ * @function contentLlmsTxt
+ * @param options {ContentLlmsTxtOptions} the site, the file's head, the registry and the API
+ *   section's links
+ * @returns {string} the llms.txt body, sections in order Docs, Guides, API, Legal; an empty
+ *   section (no entries, no extras, no `api` links) is left out
+ */
+export declare const contentLlmsTxt: (options: ContentLlmsTxtOptions) => string;
+/** contentLlmsFull's options. */
+export type ContentLlmsFullOptions = {
+    site: Site;
+    title: string;
+    summary?: string;
+    content: Content;
+    /** Reads one entry's Markdown, usually `readContentMarkdown` from `docs/files`. */
+    read: (section: ContentSection, slug: string) => Promise<string>;
+    /** Parts written before the registry's entries, like a brief introduction. */
+    before?: readonly LlmsFullPart[];
+    /** Parts written after the registry's entries, like extras an app reads on its own. */
+    after?: readonly LlmsFullPart[];
+};
+/**
+ * @function contentLlmsFull
+ * @param options {ContentLlmsFullOptions} the site, the file's head, the registry, a reader and
+ *   extra parts to place before and after the registry's entries
+ * @returns {Promise<string>} the llms-full.txt body: `before`, then every registry entry in
+ *   section order (title, its absolute page URL, and `read`'s Markdown with its own leading H1
+ *   stripped, since `llmsFull` writes the part title as the H1), then `after`
+ */
+export declare const contentLlmsFull: (options: ContentLlmsFullOptions) => Promise<string>;
+/**
+ * @function contentSitemap
+ * @param content {Content} a registry from `defineContent`
+ * @returns {SitemapRecord[]} one record per non-empty section: the section's index path (like
+ *   "/docs") with `lastModified` set to the newest `lastUpdated` among its entries and extras
+ *   (omitted when none have one), then each entry with its own `lastUpdated`, then each extra
+ *   with its own `lastUpdated` when set
+ */
+export declare const contentSitemap: (content: Content) => SitemapRecord[];
+/** One Next.js rewrite rule: `source` and `destination`. */
+export type ContentRewriteRule = {
+    source: string;
+    destination: string;
+};
+/**
+ * @function contentRewrites
+ * @returns {ContentRewriteRule[]} the one rule that mirrors a content page's ".md" URL
+ *   (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...)
+ */
+export declare const contentRewrites: () => ContentRewriteRule[];

package/dist/docs/crawl.js

@@ -0,0 +1,115 @@
+/**
+ * @file src/docs/crawl.ts
+ * @desc /llms.txt, /llms-full.txt, sitemap entries and the ".md" mirror rewrite, built straight
+ *       from a content registry. Pure: no node: imports or file reads here (an app's
+ *       `read`/`readContentMarkdown` provides the Markdown), so it runs anywhere `docs` does.
+ *       Reuses `llmsTxt`/`llmsFull` from `../seo/llms.js` for formatting, so escaping and section
+ *       shape stay the same as every other haruhime.moe crawl file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { llmsFull, llmsTxt, } from "../seo/llms.js";
+import { absoluteUrl } from "../seo/site.js";
+import { contentPath, markdownPath, SECTION_LABELS, } from "./registry.js";
+const sectionLinks = (site, content, section) => [
+    ...content.entries[section].map((entry) => ({
+        title: entry.title,
+        url: absoluteUrl(site, markdownPath(section, entry.slug)),
+        note: entry.description,
+    })),
+    ...content.extra[section].map((extra) => ({
+        title: extra.title,
+        url: absoluteUrl(site, extra.markdownHref ?? extra.href),
+        note: extra.description,
+    })),
+];
+/**
+ * @function contentLlmsTxt
+ * @param options {ContentLlmsTxtOptions} the site, the file's head, the registry and the API
+ *   section's links
+ * @returns {string} the llms.txt body, sections in order Docs, Guides, API, Legal; an empty
+ *   section (no entries, no extras, no `api` links) is left out
+ */
+export const contentLlmsTxt = (options) => {
+    const { site, title, summary, notes, content, api = [] } = options;
+    const sections = [
+        { heading: SECTION_LABELS.docs, links: sectionLinks(site, content, "docs") },
+        { heading: SECTION_LABELS.guides, links: sectionLinks(site, content, "guides") },
+        {
+            heading: "API",
+            links: api.map(({ title: t, url, note }) => ({ title: t, url, ...(note ? { note } : {}) })),
+        },
+        { heading: SECTION_LABELS.legal, links: sectionLinks(site, content, "legal") },
+    ];
+    return llmsTxt({ title, summary, ...(notes ? { notes } : {}), sections });
+};
+/** A leading "# ...\n" line, and the one blank line after it, if any. */
+const LEADING_HEADING = /^# [^\n]*\n\n?/;
+const stripLeadingHeading = (markdown) => markdown.replace(LEADING_HEADING, "");
+/**
+ * @function contentLlmsFull
+ * @param options {ContentLlmsFullOptions} the site, the file's head, the registry, a reader and
+ *   extra parts to place before and after the registry's entries
+ * @returns {Promise<string>} the llms-full.txt body: `before`, then every registry entry in
+ *   section order (title, its absolute page URL, and `read`'s Markdown with its own leading H1
+ *   stripped, since `llmsFull` writes the part title as the H1), then `after`
+ */
+export const contentLlmsFull = async (options) => {
+    const { site, title, summary, content, read, before = [], after = [] } = options;
+    const parts = [...before];
+    for (const section of content.sections) {
+        for (const entry of content.entries[section]) {
+            const markdown = await read(section, entry.slug);
+            parts.push({
+                title: entry.title,
+                url: absoluteUrl(site, contentPath(section, entry.slug)),
+                markdown: stripLeadingHeading(markdown),
+            });
+        }
+    }
+    parts.push(...after);
+    return llmsFull(parts, { title, ...(summary ? { summary } : {}) });
+};
+const newestDate = (dates) => dates.length ? dates.reduce((newest, date) => (date > newest ? date : newest)) : undefined;
+/**
+ * @function contentSitemap
+ * @param content {Content} a registry from `defineContent`
+ * @returns {SitemapRecord[]} one record per non-empty section: the section's index path (like
+ *   "/docs") with `lastModified` set to the newest `lastUpdated` among its entries and extras
+ *   (omitted when none have one), then each entry with its own `lastUpdated`, then each extra
+ *   with its own `lastUpdated` when set
+ */
+export const contentSitemap = (content) => {
+    const records = [];
+    for (const section of content.sections) {
+        const entries = content.entries[section];
+        const extras = content.extra[section];
+        const newest = newestDate([
+            ...entries.map((entry) => entry.lastUpdated),
+            ...extras.flatMap((extra) => (extra.lastUpdated ? [extra.lastUpdated] : [])),
+        ]);
+        records.push({ path: `/${section}`, ...(newest ? { lastModified: newest } : {}) });
+        for (const entry of entries) {
+            records.push({ path: contentPath(section, entry.slug), lastModified: entry.lastUpdated });
+        }
+        for (const extra of extras) {
+            records.push({
+                path: extra.href,
+                ...(extra.lastUpdated ? { lastModified: extra.lastUpdated } : {}),
+            });
+        }
+    }
+    return records;
+};
+/**
+ * @function contentRewrites
+ * @returns {ContentRewriteRule[]} the one rule that mirrors a content page's ".md" URL
+ *   (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...)
+ */
+export const contentRewrites = () => [
+    {
+        source: "/:section(docs|guides|legal)/:slug([a-z0-9-]+).md",
+        destination: "/:section/:slug/md",
+    },
+];

package/dist/docs/files/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file src/docs/files/index.ts
+ * @desc @haruhimemoe/next-kit/docs/files: reads the markdown files a content registry's entries
+ *       point at. Server only: loads node:fs (kept out of the pure `docs` entry point on
+ *       purpose). A section's markdown source lives at "<root>/content/<section>/<slug>.mdx";
+ *       `readContentMarkdown` converts one with `mdxToMarkdown`, and `contentFileDrift` compares
+ *       the registry against the files actually on disk.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type Content, type ContentSection, type MarkdownOptions } from "../index.js";
+/**
+ * @function readContentMarkdown
+ * @param content {Content} a validated registry from `defineContent`
+ * @param section {ContentSection} the section the entry lives under
+ * @param slug {string} the entry's slug
+ * @param options {{ root?: string; siteUrl: string; transforms?: MarkdownOptions["transforms"] }}
+ *   `root` defaults to `process.cwd()`; the source file is read from
+ *   "<root>/content/<section>/<slug>.mdx"
+ * @returns {Promise<string | null>} the converted markdown, or null when the slug isn't
+ *   registered in `content`
+ * @throws {Error} the file system's ENOENT when the slug is registered but its file is missing
+ */
+export declare const readContentMarkdown: (content: Content, section: ContentSection, slug: string, options: {
+    root?: string;
+    siteUrl: string;
+    transforms?: MarkdownOptions["transforms"];
+}) => Promise<string | null>;
+/**
+ * @function contentFileDrift
+ * @param content {Content} a validated registry from `defineContent`
+ * @param options {{ root?: string }} `root` defaults to `process.cwd()`
+ * @returns {{ missingFiles: string[]; unregistered: string[] }} `missingFiles` lists every
+ *   registered entry with no ".mdx" file on disk (like "guides/x.mdx"); `unregistered` lists
+ *   every ".mdx" file on disk with no matching registry entry
+ */
+export declare const contentFileDrift: (content: Content, options?: {
+    root?: string;
+}) => {
+    missingFiles: string[];
+    unregistered: string[];
+};

package/dist/docs/files/index.js

@@ -0,0 +1,74 @@
+/**
+ * @file src/docs/files/index.ts
+ * @desc @haruhimemoe/next-kit/docs/files: reads the markdown files a content registry's entries
+ *       point at. Server only: loads node:fs (kept out of the pure `docs` entry point on
+ *       purpose). A section's markdown source lives at "<root>/content/<section>/<slug>.mdx";
+ *       `readContentMarkdown` converts one with `mdxToMarkdown`, and `contentFileDrift` compares
+ *       the registry against the files actually on disk.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONTENT_SECTIONS, findEntry, mdxToMarkdown, } from "../index.js";
+const MDX_EXTENSION = ".mdx";
+/** Where an entry's source markdown lives, relative to root: "<section>/<slug>.mdx". */
+const entryFile = (section, slug) => `${section}/${slug}${MDX_EXTENSION}`;
+/**
+ * @function readContentMarkdown
+ * @param content {Content} a validated registry from `defineContent`
+ * @param section {ContentSection} the section the entry lives under
+ * @param slug {string} the entry's slug
+ * @param options {{ root?: string; siteUrl: string; transforms?: MarkdownOptions["transforms"] }}
+ *   `root` defaults to `process.cwd()`; the source file is read from
+ *   "<root>/content/<section>/<slug>.mdx"
+ * @returns {Promise<string | null>} the converted markdown, or null when the slug isn't
+ *   registered in `content`
+ * @throws {Error} the file system's ENOENT when the slug is registered but its file is missing
+ */
+export const readContentMarkdown = async (content, section, slug, options) => {
+    const entry = findEntry(content, section, slug);
+    if (!entry)
+        return null;
+    const root = options.root ?? process.cwd();
+    const source = await readFile(join(root, "content", entryFile(section, slug)), "utf8");
+    return mdxToMarkdown(source, {
+        title: entry.title,
+        siteUrl: options.siteUrl,
+        ...(options.transforms !== undefined ? { transforms: options.transforms } : {}),
+    });
+};
+/**
+ * @function contentFileDrift
+ * @param content {Content} a validated registry from `defineContent`
+ * @param options {{ root?: string }} `root` defaults to `process.cwd()`
+ * @returns {{ missingFiles: string[]; unregistered: string[] }} `missingFiles` lists every
+ *   registered entry with no ".mdx" file on disk (like "guides/x.mdx"); `unregistered` lists
+ *   every ".mdx" file on disk with no matching registry entry
+ */
+export const contentFileDrift = (content, options = {}) => {
+    const root = options.root ?? process.cwd();
+    const missingFiles = [];
+    const unregistered = [];
+    for (const section of CONTENT_SECTIONS) {
+        const slugs = new Set(content.entries[section].map((entry) => entry.slug));
+        for (const slug of slugs) {
+            if (!existsSync(join(root, "content", entryFile(section, slug))))
+                missingFiles.push(entryFile(section, slug));
+        }
+        let files;
+        try {
+            files = readdirSync(join(root, "content", section));
+        }
+        catch {
+            files = [];
+        }
+        for (const file of files) {
+            if (file.endsWith(MDX_EXTENSION) && !slugs.has(file.slice(0, -MDX_EXTENSION.length)))
+                unregistered.push(`${section}/${file}`);
+        }
+    }
+    return { missingFiles, unregistered };
+};

package/dist/docs/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file src/docs/index.ts
+ * @desc @haruhimemoe/next-kit/docs: the content registry (sections, entries, app-made extras),
+ *       the path helpers every docs, guides and legal page is built from, mdxToMarkdown's
+ *       MDX-to-plain-Markdown conversion, and the crawl helpers (llms.txt, llms-full.txt, sitemap
+ *       entries, the ".md" mirror rewrite) built from the registry. Pure: no node: imports, so it
+ *       runs in any route, edge or browser. File-backed markdown reading lives under the separate
+ *       `docs/files` entry point.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+export { type ContentApiLink, type ContentLlmsFullOptions, type ContentLlmsTxtOptions, type ContentRewriteRule, contentLlmsFull, contentLlmsTxt, contentRewrites, contentSitemap, } from "./crawl.js";
+export { type MarkdownOptions, mdxToMarkdown } from "./markdown.js";
+export { CONTENT_SECTIONS, type Content, type ContentEntry, type ContentInput, type ContentSection, contentParams, contentPath, defineContent, type ExtraEntry, findEntry, type HowToStep, markdownPath, SECTION_LABELS, } from "./registry.js";

package/dist/docs/index.js

@@ -0,0 +1,15 @@
+/**
+ * @file src/docs/index.ts
+ * @desc @haruhimemoe/next-kit/docs: the content registry (sections, entries, app-made extras),
+ *       the path helpers every docs, guides and legal page is built from, mdxToMarkdown's
+ *       MDX-to-plain-Markdown conversion, and the crawl helpers (llms.txt, llms-full.txt, sitemap
+ *       entries, the ".md" mirror rewrite) built from the registry. Pure: no node: imports, so it
+ *       runs in any route, edge or browser. File-backed markdown reading lives under the separate
+ *       `docs/files` entry point.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+export { contentLlmsFull, contentLlmsTxt, contentRewrites, contentSitemap, } from "./crawl.js";
+export { mdxToMarkdown } from "./markdown.js";
+export { CONTENT_SECTIONS, contentParams, contentPath, defineContent, findEntry, markdownPath, SECTION_LABELS, } from "./registry.js";