@kirchdev/duxt 0.1.0

package/server/routes/llms.txt.get.ts

@@ -0,0 +1,63 @@
+import { queryCollection } from '@nuxt/content/nitro';
+// Imported by path, not auto-import: app/ belongs to the Vue app, and Nitro
+// does not see its utils. The defaults have to come from the same file the
+// pages use, or the two descriptions drift apart.
+import { duxtDefaults, mergeDuxtConfig } from '../../app/utils/duxt-config';
+import { resolveServerTexts } from '../utils/duxt-server-text';
+
+/**
+ * llms.txt — the site's own map, for a model reading it.
+ *
+ * The convention (llmstxt.org) is a Markdown index: an H1 with the site name,
+ * a blockquote summary, then linked sections. It is generated from the same
+ * collection the pages render from, so it cannot drift from what is published.
+ */
+export default defineEventHandler(async (event) => {
+  const appConfig = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  // Resolved here because Nitro has no i18n: without it the description is
+  // printed as the translation key it is.
+  const duxt = resolveServerTexts(
+    mergeDuxtConfig(appConfig.duxt, duxtDefaults)
+  );
+
+  // Every collection the manifest names, not just `docs`: a versioned site
+  // has none by that name, and llms.txt is the whole site's index.
+  const collections = duxt.resolvedSources?.length
+    ? duxt.resolvedSources.map((source) => source.collection)
+    : ['docs'];
+
+  const pages = (
+    await Promise.all(
+      collections.map((name) =>
+        // Cast from Content's own signature: the collection name is data
+        // from the manifest, and the key union is generated per site.
+        queryCollection(event, name as Parameters<typeof queryCollection>[1])
+          .select('path', 'title', 'description')
+          .all()
+      )
+    )
+  ).flat();
+
+  const origin = getRequestURL(event).origin;
+
+  const lines = [
+    `# ${duxt.title}`,
+    '',
+    `> ${duxt.landing?.description ?? 'Documentation.'}`,
+    '',
+    '## Pages',
+    '',
+    ...pages
+      .filter((page) => page.path)
+      .sort((a, b) => a.path!.localeCompare(b.path!))
+      .map(
+        (page) =>
+          `- [${page.title ?? page.path}](${origin}${page.path})` +
+          (page.description ? `: ${page.description}` : '')
+      ),
+    ''
+  ];
+
+  setHeader(event, 'content-type', 'text/plain; charset=utf-8');
+  return lines.join('\n');
+});

package/server/routes/rss.xml.get.ts

@@ -0,0 +1,125 @@
+import { queryCollection } from '@nuxt/content/nitro';
+import { duxtDefaults, mergeDuxtConfig } from '../../app/utils/duxt-config';
+import { resolveServerTexts } from '../utils/duxt-server-text';
+
+/**
+ * An RSS feed over one section — a changelog, a release log, a blog.
+ *
+ * Not over the whole documentation. A feed is a list of things that HAPPENED,
+ * and a reference page being edited is not an event; a site publishing every
+ * page edit as an item teaches its readers to unsubscribe. So the feed is off
+ * until `duxt.feed.path` names the section whose pages are events, and empty
+ * rather than missing before that: a feed client should be told there is
+ * nothing here, not that the feed is gone.
+ *
+ * Ordering is by the page's own `date`, falling back to the last commit that
+ * touched it — which `modules/git-meta.ts` has already put on the page.
+ */
+const escape = (value: string) =>
+  value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&apos;'
+      })[character] ?? character
+  );
+
+export default defineEventHandler(async (event) => {
+  const appConfig = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  // Resolved here because Nitro has no i18n: without it the description is
+  // printed as the translation key it is.
+  const duxt = resolveServerTexts(
+    mergeDuxtConfig(appConfig.duxt, duxtDefaults)
+  );
+
+  const origin = getRequestURL(event).origin;
+  const feed = duxt.feed;
+  const title = typeof feed?.title === 'string' ? feed.title : undefined;
+
+  const items: {
+    path: string;
+    title: string;
+    description?: string;
+    date?: string;
+  }[] = [];
+
+  if (feed?.path) {
+    const collections = duxt.resolvedSources?.length
+      ? duxt.resolvedSources
+          // One version of a changelog, not four. The default version is the
+          // one a feed reader wants; the others repeat every entry.
+          .filter((source) => source.isDefault)
+          .map((source) => source.collection)
+      : ['docs'];
+
+    const pages = (
+      await Promise.all(
+        collections.map((name) =>
+          queryCollection(event, name as Parameters<typeof queryCollection>[1])
+            .select('path', 'title', 'description', 'date', 'lastUpdated')
+            .all()
+        )
+      )
+    ).flat() as {
+      path?: string;
+      title?: string;
+      description?: string;
+      date?: string;
+      lastUpdated?: string;
+    }[];
+
+    for (const page of pages) {
+      if (!page.path?.startsWith(feed.path)) continue;
+      if (page.path === feed.path) continue;
+
+      items.push({
+        path: page.path,
+        title: page.title ?? page.path,
+        description: page.description,
+        date: page.date ?? page.lastUpdated
+      });
+    }
+
+    items.sort((a, b) => (b.date ?? '').localeCompare(a.date ?? ''));
+  }
+
+  const body = items
+    .map(
+      (item) => `    <item>
+      <title>${escape(item.title)}</title>
+      <link>${escape(origin + item.path)}</link>
+      <guid isPermaLink="true">${escape(origin + item.path)}</guid>${
+        item.description
+          ? `\n      <description>${escape(item.description)}</description>`
+          : ''
+      }${
+        item.date
+          ? `\n      <pubDate>${new Date(item.date).toUTCString()}</pubDate>`
+          : ''
+      }
+    </item>`
+    )
+    .join('\n');
+
+  setHeader(event, 'content-type', 'application/rss+xml; charset=utf-8');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escape(title ?? String(duxt.title))}</title>
+    <link>${escape(origin)}</link>
+    <description>${escape(
+      typeof duxt.landing?.description === 'string'
+        ? duxt.landing.description
+        : 'Documentation.'
+    )}</description>
+    <atom:link href="${escape(`${origin}/rss.xml`)}" rel="self" type="application/rss+xml" />
+${body}
+  </channel>
+</rss>
+`;
+});

package/server/utils/duxt-server-text.ts

@@ -0,0 +1,46 @@
+import enDefaults from '../../i18n/locales/en/duxt/defaults.json' with { type: 'json' };
+import { resolveDuxtTexts } from '../../app/utils/duxt-text';
+
+/**
+ * Resolve the config's text fields on the server, where there is no i18n.
+ *
+ * `llms.txt` and the feed are Nitro routes: no Vue app, no `useI18n`, and so no
+ * translator. Before this, both printed the KEY — a feed whose description was
+ * the dotted path itself, and an llms.txt that told a model the same. Falling
+ * back to the layer's English messages is the honest answer: it
+ * is what `fallbackLocale` already says a missing translation resolves to, and
+ * these routes have no locale of their own to serve anyway.
+ *
+ * Only the layer's own defaults are looked up. A consumer's keys live in the
+ * consumer's locale files, which Nitro has no reader for — those pass through
+ * as written, exactly as an unregistered key does in the browser.
+ */
+const messages = enDefaults as Record<string, unknown>;
+
+function lookup(key: string): string | undefined {
+  let node: unknown = messages;
+
+  for (const part of key.split('.')) {
+    if (!node || typeof node !== 'object') return undefined;
+    node = (node as Record<string, unknown>)[part];
+  }
+
+  return typeof node === 'string' ? node : undefined;
+}
+
+export function resolveServerTexts<T>(config: T): T {
+  return resolveDuxtTexts(config, 'en-GB', lookup);
+}
+
+/**
+ * The Markdown body without its frontmatter block.
+ *
+ * Content's `rawbody` is the file as it sits on disk, frontmatter included. A
+ * reader wants the prose; a model handed `---\ntitle: …\n---` reads a page
+ * whose first heading is a YAML fence.
+ */
+export function stripFrontmatter(body: string): string {
+  const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(body);
+
+  return match ? body.slice(match[0].length) : body;
+}

package/sources-git.ts

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import type { DuxtSource } from './sources-resolve';
+import { isLatestRef, newestTag, repoUrl } from './sources-resolve';
+
+/**
+ * Resolve the `latest` shorthand into the tag it means.
+ *
+ * Node-only, and separate from `sources-resolve.ts` for the same reason
+ * `sources.ts` is: that file is read by the browser half of the layer, and
+ * `node:child_process` cannot be bundled for it.
+ *
+ * Both halves of the build must agree on the answer — `sources.ts` declares the
+ * collections, `modules/config.ts` resolves the manifest the theme reads — so
+ * the answer is cached per repository for the life of the process. Two calls to
+ * `git ls-remote` a second apart could otherwise straddle a release and leave
+ * the site with a collection no route points at.
+ */
+const cache = new Map<string, string[]>();
+
+/**
+ * What a repository URL is allowed to look like before it is handed to `git`.
+ *
+ * An allowlist rather than a check for a leading dash, because the argument
+ * reaches a command: `git ls-remote --upload-pack=<anything>` runs that
+ * anything, and every value that is not a URL is easier to reject than to
+ * reason about. One quantifier over one character class, so the test itself
+ * cannot be the next finding.
+ */
+const REMOTE_URL = /^(?:https?:\/\/|ssh:\/\/|git@)[\w.~:/?#@!$&'()*+,;=%-]+$/;
+
+/** The tags of a remote, or nothing when its URL is not one we will run. */
+function remoteTags(repo: string): string {
+  const url = repoUrl(repo);
+
+  if (!REMOTE_URL.test(url)) {
+    throw new Error(`duxt: refusing to read tags from ${JSON.stringify(url)}`);
+  }
+
+  return execFileSync(
+    'git',
+    // `--end-of-options` so a URL that survived the test above is still read as
+    // a URL and never as an option.
+    ['ls-remote', '--tags', '--refs', '--end-of-options', url],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+  );
+}
+
+function tagsOf(repo: string | undefined): string[] {
+  const key = repo ?? '.';
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  let tags: string[] = [];
+
+  try {
+    const output = repo
+      ? remoteTags(repo)
+      : execFileSync('git', ['tag', '--list'], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore']
+        });
+
+    tags = output
+      .split('\n')
+      .map((line) => line.trim().split(/\s+/).pop() ?? '')
+      .map((ref) => ref.replace(/^refs\/tags\//, ''))
+      .filter(Boolean);
+  } catch {
+    // Reported by the caller, which knows which source asked.
+    tags = [];
+  }
+
+  cache.set(key, tags);
+  return tags;
+}
+
+/**
+ * The source list with every `latest` replaced by a concrete tag.
+ *
+ * Called before `resolveSources` by both build-time entry points, so the
+ * resolver itself stays pure and testable — it never learns that git exists.
+ */
+export function resolveLatestRefs(sources: DuxtSource[]): DuxtSource[] {
+  return sources.map((source) => {
+    if (!source.refs?.some(isLatestRef)) return source;
+
+    const newest = newestTag(tagsOf(source.repo));
+
+    if (!newest) {
+      throw new Error(
+        `duxt: refs: ['latest'] on ${source.repo ?? 'this repository'} found ` +
+          'no tags to choose from. Name a tag explicitly, or drop the entry.'
+      );
+    }
+
+    return {
+      ...source,
+      refs: source.refs.map((ref) =>
+        isLatestRef(ref)
+          ? {
+              tag: newest,
+              // The URL keeps saying `latest`, so a bookmark survives the next
+              // release; only the ref underneath moves. `label` is what the
+              // switcher and the prefix are built from.
+              label:
+                typeof ref === 'object' ? (ref.label ?? 'latest') : 'latest',
+              status: typeof ref === 'object' ? ref.status : undefined
+            }
+          : ref
+      )
+    };
+  });
+}