@kirchdev/duxt 0.1.0

package/server/devtools/sources.ts

@@ -0,0 +1,122 @@
+import type { H3Event } from 'h3';
+import { queryCollection } from '@nuxt/content/nitro';
+import { splitLocalePath } from '../../app/utils/locale-path';
+import { sourcesForRoute } from '../../sources-resolve';
+import { context, resolvedSources } from './context';
+import type { FoundPage } from './render/sources';
+import { renderPaths, renderSources, renderVersions } from './render/sources';
+
+/**
+ * The queries behind the three source panels.
+ *
+ * The resolver is pure and already tested, so none of this reimplements it: the
+ * panels call the same functions the theme calls, and hand what came back to
+ * `render/sources.ts`. A panel that computed its own answer would be able to
+ * disagree with the site, which is the one thing a debugging view must not do.
+ */
+
+/** Content stores a page under its full path, prefix included. */
+const collectionsOf = () =>
+  resolvedSources().map((source) => source.collection) as Parameters<
+    typeof queryCollection
+  >[1][];
+
+/** Every page path the site serves, by collection. */
+async function pathsByCollection(
+  event: H3Event
+): Promise<Map<string, string[]>> {
+  const result = new Map<string, string[]>();
+
+  await Promise.all(
+    collectionsOf().map(async (name) => {
+      try {
+        const pages = await queryCollection(event, name)
+          .select('path')
+          .order('path', 'ASC')
+          .all();
+
+        result.set(
+          name,
+          pages.map((page) => page.path)
+        );
+      } catch {
+        // A collection Content dropped is exactly what the Checks panel is for;
+        // here it is simply a collection with no pages.
+        result.set(name, []);
+      }
+    })
+  );
+
+  return result;
+}
+
+/** The sources table — what a consumer wrote, as the site resolved it. */
+export function sourcesPanel(): string {
+  return renderSources(resolvedSources(), context.appConfigFile);
+}
+
+/** The path debugger: which source claims a URL, and what it finds there. */
+export async function pathsPanel(
+  event: H3Event,
+  input: string
+): Promise<string> {
+  const sources = resolvedSources();
+  const locales = context.locales;
+
+  if (!input) {
+    return renderPaths({
+      input,
+      locales,
+      fallbackLocale: context.fallbackLocale,
+      sources,
+      found: null,
+      byCollection: new Map()
+    });
+  }
+
+  // The same two pure calls the renderer walks the reader through, repeated
+  // here only to know WHICH collection to query. Cheap, and it keeps the
+  // renderer free of the database.
+  //
+  // The locale is carried into the choice rather than thrown away with the
+  // segment: a translation lives under the SAME prefix as its original, so a
+  // lookup given only the stripped path answers with whichever collection
+  // sorted first — and told the reader about `docs` when they pasted a `/de/`
+  // URL.
+  const { locale, path: documentationPath } = splitLocalePath(input, locales);
+  const source = sourcesForRoute(
+    documentationPath,
+    locale,
+    sources,
+    context.fallbackLocale
+  )[0];
+
+  let found: FoundPage | null = null;
+
+  if (source) {
+    try {
+      found = (await queryCollection(
+        event,
+        source.collection as Parameters<typeof queryCollection>[1]
+      )
+        .path(documentationPath)
+        .first()) as unknown as FoundPage | null;
+    } catch {
+      found = null;
+    }
+  }
+
+  return renderPaths({
+    input,
+    locales,
+    fallbackLocale: context.fallbackLocale,
+    sources,
+    found,
+    byCollection: await pathsByCollection(event)
+  });
+}
+
+/** Which version — and which language — carries which page. */
+export async function versionsPanel(event: H3Event): Promise<string> {
+  return renderVersions(resolvedSources(), await pathsByCollection(event));
+}

package/server/devtools/system.ts

@@ -0,0 +1,178 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { context } from './context';
+import type { CacheEntry, LocaleFile, RedirectRule } from './render/system';
+import {
+  renderCache,
+  renderConfig,
+  renderI18n,
+  renderRedirects
+} from './render/system';
+
+/**
+ * What the panels about the machinery read: the merged config, the message
+ * catalogues, Content's download cache and the redirects that shipped.
+ *
+ * Each answers a question whose answer exists only as a side effect somewhere —
+ * inside a defu call, across seven JSON files, in a directory nobody opens, in
+ * a route-rule table generated at build time. This half does the reading;
+ * `render/system.ts` turns it into tables.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Config                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/** The merged config, with the side of the merge each value came from. */
+export function configPanel(): string {
+  const { duxt } = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+
+  return renderConfig((duxt ?? {}) as unknown as Record<string, unknown>);
+}
+
+/* -------------------------------------------------------------------------- */
+/* i18n                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/** Every message key of every locale file the layer ships. */
+export function i18nPanel(): string {
+  const root = join(context.layerDir, 'i18n/locales');
+
+  let dirs: string[];
+  try {
+    dirs = readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return '<div class="note">No <code>i18n/locales</code> directory in the layer.</div>';
+  }
+
+  const files: LocaleFile[] = dirs.map((dir) => ({
+    dir,
+    keys: [...keysOf(join(root, dir, 'duxt'))]
+  }));
+
+  return renderI18n({
+    files,
+    locales: context.locales,
+    defaultLocale: context.defaultLocale
+  });
+}
+
+function keysOf(namespaces: string): Set<string> {
+  const keys = new Set<string>();
+
+  let files: string[];
+  try {
+    files = readdirSync(namespaces).filter((file) => file.endsWith('.json'));
+  } catch {
+    return keys;
+  }
+
+  for (const file of files) {
+    try {
+      flatten(
+        JSON.parse(readFileSync(join(namespaces, file), 'utf8')) as unknown,
+        '',
+        keys
+      );
+    } catch {
+      keys.add(`${file}: unreadable`);
+    }
+  }
+
+  return keys;
+}
+
+function flatten(node: unknown, prefix: string, out: Set<string>): void {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    if (prefix) out.add(prefix);
+    return;
+  }
+
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    flatten(value, prefix ? `${prefix}.${key}` : key, out);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Cache                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Content's download cache, and a way to drop one entry. */
+export function cachePanel(message?: string): string {
+  let entries: CacheEntry[] | undefined;
+
+  try {
+    entries = readdirSync(context.dataDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => {
+        const path = join(context.dataDir, entry.name);
+        return {
+          name: entry.name,
+          size: sizeOf(path),
+          modified: statSync(path).mtime
+        };
+      })
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    entries = undefined;
+  }
+
+  return renderCache({ dataDir: context.dataDir, entries, message });
+}
+
+function sizeOf(path: string): number {
+  let total = 0;
+
+  for (const entry of readdirSync(path, { withFileTypes: true })) {
+    const child = join(path, entry.name);
+    total += entry.isDirectory() ? sizeOf(child) : statSync(child).size;
+  }
+
+  return total;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Redirects                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Every redirect the server ships, and which of them the layer wrote.
+ *
+ * Read rather than recomputed on purpose: a rule that was generated and a rule
+ * that shipped are different claims, and only the second one redirects anybody.
+ * Reading them back means reading EVERY module's, so `modules/redirects.ts`
+ * records which paths are its own beside them — nothing in a route rule says
+ * who wrote it.
+ */
+export function redirectsPanel(): string {
+  const config = useRuntimeConfig() as {
+    nitro?: { routeRules?: Record<string, { redirect?: unknown }> };
+    duxt?: { redirects?: string[] };
+  };
+
+  const rules = config.nitro?.routeRules;
+  if (!rules) return renderRedirects();
+
+  const ours = new Set(config.duxt?.redirects ?? []);
+
+  const redirects: RedirectRule[] = Object.entries(rules)
+    .filter(([, rule]) => rule?.redirect)
+    .map(([from, rule]) => {
+      const redirect = rule.redirect as
+        | string
+        | { to?: string; statusCode?: number };
+
+      return {
+        from,
+        to: typeof redirect === 'string' ? redirect : (redirect.to ?? '?'),
+        status:
+          typeof redirect === 'string' ? '302' : (redirect.statusCode ?? 302),
+        mine: ours.has(from)
+      };
+    });
+
+  return renderRedirects(redirects);
+}

package/server/mcp/tools/list-pages.ts

@@ -0,0 +1,52 @@
+import { queryCollection } from '@nuxt/content/nitro';
+
+/**
+ * The documentation's table of contents, for a model.
+ *
+ * Built on @nuxtjs/mcp-toolkit rather than a JSON endpoint of our own: it
+ * speaks the actual protocol through the official SDK, so a client connects to
+ * `/mcp` instead of someone writing a server around our shape.
+ */
+/** Every collection the manifest names — a versioned site has none called `docs`. */
+function duxtCollections(): 'docs'[] {
+  const { duxt } = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  const names = duxt?.resolvedSources?.length
+    ? duxt.resolvedSources.map((source) => source.collection)
+    : ['docs'];
+  return names as 'docs'[];
+}
+
+export default defineMcpTool({
+  name: 'list_pages',
+  title: 'List documentation pages',
+  description:
+    'Every page of this documentation with its path, title and description. ' +
+    'Start here, then read a page with `read_page`.',
+  annotations: { readOnlyHint: true },
+
+  // A tool without an `inputSchema` is called with ONE argument: the SDK hands
+  // the handler `extra` directly rather than `(args, extra)`. Written the other
+  // way round, `extra` was undefined and every call failed on `extra.event`.
+  async handler(extra) {
+    const pages = (
+      await Promise.all(
+        duxtCollections().map((name) =>
+          queryCollection(extra.event, name)
+            .select('path', 'title', 'description')
+            .all()
+        )
+      )
+    ).flat();
+
+    const listing = pages
+      .filter((page) => page.path)
+      .sort((a, b) => a.path!.localeCompare(b.path!))
+      .map(
+        (page) =>
+          `- ${page.path} — ${page.title}${page.description ? `: ${page.description}` : ''}`
+      )
+      .join('\n');
+
+    return { content: [{ type: 'text', text: listing }] };
+  }
+});

package/server/mcp/tools/read-page.ts

@@ -0,0 +1,57 @@
+import { queryCollection } from '@nuxt/content/nitro';
+import { z } from 'zod';
+
+/**
+ * One page's prose. Returns the stored content rather than rendered HTML — a
+ * model reading documentation wants the text, not the theme around it.
+ */
+/** Every collection the manifest names — a versioned site has none called `docs`. */
+function duxtCollections(): 'docs'[] {
+  const { duxt } = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  const names = duxt?.resolvedSources?.length
+    ? duxt.resolvedSources.map((source) => source.collection)
+    : ['docs'];
+  return names as 'docs'[];
+}
+
+export default defineMcpTool({
+  name: 'read_page',
+  title: 'Read a documentation page',
+  description: 'The full content of one page. Paths come from `list_pages`.',
+  annotations: { readOnlyHint: true },
+
+  inputSchema: {
+    path: z.string().describe('Page path, for example /guide/deploying')
+  },
+
+  async handler({ path }, extra) {
+    // Try each collection: a path carries its own prefix, so at most one has it.
+    const found = await Promise.all(
+      duxtCollections().map((name) =>
+        queryCollection(extra.event, name).path(path).first()
+      )
+    );
+    const page = found.find(Boolean);
+
+    if (!page) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No page at ${path}. Use \`list_pages\` for valid paths.`
+          }
+        ],
+        isError: true
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `# ${page.title}\n\n${page.description ?? ''}\n\n${JSON.stringify(page.body)}`
+        }
+      ]
+    };
+  }
+});

package/server/mcp/tools/search-docs.ts

@@ -0,0 +1,74 @@
+import { queryCollection } from '@nuxt/content/nitro';
+import { z } from 'zod';
+
+/**
+ * Search, so a model does not have to read every page to find one.
+ *
+ * A LIKE over title and description rather than the FTS index the browser
+ * uses: that index is built client-side from the collection dump, and a server
+ * tool has the database itself.
+ */
+/** Every collection the manifest names — a versioned site has none called `docs`. */
+function duxtCollections(): 'docs'[] {
+  const { duxt } = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  const names = duxt?.resolvedSources?.length
+    ? duxt.resolvedSources.map((source) => source.collection)
+    : ['docs'];
+  return names as 'docs'[];
+}
+
+export default defineMcpTool({
+  name: 'search_docs',
+  title: 'Search the documentation',
+  description: 'Find pages whose title or description matches a term.',
+  annotations: { readOnlyHint: true },
+
+  inputSchema: {
+    query: z.string().describe('What to look for')
+  },
+
+  async handler({ query }, extra) {
+    const term = `%${query}%`;
+
+    // Both conditions in ONE group. Content joins the query's top-level
+    // conditions with AND regardless of how each was added, so a `where()`
+    // followed by an `orWhere()` asks for a term in the title AND in the
+    // description — which matched nothing at all. Inside a group the operator
+    // is the one the group was opened with, so `orWhere` gives title OR
+    // description.
+    const pages = (
+      await Promise.all(
+        duxtCollections().map((name) =>
+          queryCollection(extra.event, name)
+            .select('path', 'title', 'description')
+            .orWhere((group) =>
+              group
+                .where('title', 'LIKE', term)
+                .where('description', 'LIKE', term)
+            )
+            .all()
+        )
+      )
+    ).flat();
+
+    if (!pages.length) {
+      return {
+        content: [{ type: 'text', text: `Nothing matches "${query}".` }]
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: pages
+            .map(
+              (page) =>
+                `- ${page.path} — ${page.title}${page.description ? `: ${page.description}` : ''}`
+            )
+            .join('\n')
+        }
+      ]
+    };
+  }
+});

package/server/middleware/raw-markdown.ts

@@ -0,0 +1,86 @@
+import { queryCollection } from '@nuxt/content/nitro';
+import { duxtDefaults, mergeDuxtConfig } from '../../app/utils/duxt-config';
+import { stripFrontmatter } from '../utils/duxt-server-text';
+
+/**
+ * `…/guide/deploying.md` serves the page's Markdown source.
+ *
+ * What "View as Markdown" opens, and what the ChatGPT and Claude links hand
+ * over — a model given the rendered HTML has to undo a layout to find a
+ * heading, and one given this reads what the author wrote.
+ *
+ * A MIDDLEWARE, not a route. Nitro's router matches path segments, and `.md` is
+ * a suffix on the last one rather than a segment of its own, so there is no
+ * pattern that means "any path ending in .md". The middleware answers those and
+ * hands everything else straight on.
+ */
+export default defineEventHandler(async (event) => {
+  const path = event.path?.split('?')[0];
+  if (!path?.endsWith('.md')) return;
+
+  const appConfig = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+  const duxt = mergeDuxtConfig(appConfig.duxt, duxtDefaults);
+
+  const wanted = stripLocale(path.slice(0, -'.md'.length));
+
+  // Longest prefix first, exactly as the app resolves a route: `/app/v2` beats
+  // `/app` on `/app/v2/guide`.
+  const sources = [...(duxt.resolvedSources ?? [])].sort(
+    (a, b) => b.prefix.length - a.prefix.length
+  );
+
+  const source =
+    sources.find(
+      (entry) =>
+        !entry.prefix ||
+        wanted === entry.prefix ||
+        wanted.startsWith(`${entry.prefix}/`)
+    ) ?? sources[0];
+
+  if (!source) return;
+
+  const page = await queryCollection(
+    event,
+    source.collection as Parameters<typeof queryCollection>[1]
+  )
+    .path(wanted)
+    .select('title', 'rawbody')
+    .first();
+
+  // No page is not this middleware's error to raise: falling through lets the
+  // app answer with its own 404, which knows how to suggest a near miss.
+  if (!page) return;
+
+  const body = (page as { rawbody?: string }).rawbody;
+  if (!body) return;
+
+  setHeader(event, 'content-type', 'text/markdown; charset=utf-8');
+  return stripFrontmatter(body).trim();
+});
+
+/**
+ * The locale segment, off.
+ *
+ * The browser is on `/de-DE/guide/deploying`; the page is `/guide/deploying`.
+ * Same distinction `stripLocalePrefix` makes in the app, made again here
+ * because Nitro has no i18n composable to ask.
+ */
+function stripLocale(path: string): string {
+  const first = path.split('/')[1];
+  if (!first) return path;
+
+  const locales = (
+    useRuntimeConfig().public as {
+      i18n?: { locales?: ({ code: string } | string)[] };
+    }
+  ).i18n?.locales;
+
+  const codes = (locales ?? []).map((locale) =>
+    typeof locale === 'string' ? locale : locale.code
+  );
+
+  if (!codes.includes(first)) return path;
+
+  const rest = path.slice(first.length + 1);
+  return rest.startsWith('/') ? rest : rest || '/';
+}

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

@@ -0,0 +1,75 @@
+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,
+  stripFrontmatter
+} from '../utils/duxt-server-text';
+
+/**
+ * llms-full.txt — the whole documentation as one Markdown file.
+ *
+ * The companion to `llms.txt`, which is an index: a model that has read the
+ * index still has to fetch sixty pages, and a model given this one has read
+ * them. The convention (llmstxt.org) names both.
+ *
+ * The Markdown as written, not the rendered HTML — which is why the collection
+ * schema asks Content for `rawbody`. An MDC block reaches the reader as the
+ * component call it is, and a code fence is still a fence.
+ */
+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 collections = duxt.resolvedSources?.length
+    ? duxt.resolvedSources.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', 'rawbody')
+          .all()
+      )
+    )
+  ).flat();
+
+  const origin = getRequestURL(event).origin;
+
+  const lines = [
+    `# ${duxt.title}`,
+    '',
+    `> ${duxt.landing?.description ?? 'Documentation.'}`,
+    ''
+  ];
+
+  for (const page of pages
+    .filter((page) => page.path)
+    .sort((a, b) => a.path!.localeCompare(b.path!))) {
+    lines.push(
+      `---`,
+      '',
+      `# ${page.title ?? page.path}`,
+      '',
+      `Source: ${origin}${page.path}`,
+      ''
+    );
+
+    if (page.description) lines.push(`> ${page.description}`, '');
+
+    // A page whose collection was declared before `rawbody` was asked for has
+    // none. Its title and URL are still worth listing.
+    const body = (page as { rawbody?: string }).rawbody;
+    if (body) lines.push(stripFrontmatter(body).trim(), '');
+  }
+
+  setHeader(event, 'content-type', 'text/plain; charset=utf-8');
+  return lines.join('\n');
+});