@kirchdev/duxt 0.1.0

package/sections.ts

@@ -0,0 +1,157 @@
+/**
+ * Generated sections, as Content collections.
+ *
+ * The build-time half of `sections-resolve.ts`, split from it for the reason
+ * `sources.ts` is split from `sources-resolve.ts`: this file imports
+ * `@nuxt/content` and reads files off disk, and the bundler refuses to follow
+ * either out of app code.
+ *
+ * A section is an ORDINARY collection — nothing here mounts a route, adds a
+ * hook or reaches into the renderer. What makes that possible is Content's
+ * custom collection source: `getKeys` and `getItem` hand it a list of files and
+ * their contents, so a type's parser can turn one artefact into as many pages as
+ * it has releases, endpoints or records, and Content parses them exactly as it
+ * parses Markdown on disk.
+ *
+ * Reading a file is all that is left here. What a finding MEANS — a missing
+ * artefact, a type that read nothing out of one — is the severity policy, and
+ * it lives in the pure half where a test can reach it.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineCollection, defineCollectionSource } from '@nuxt/content';
+import type {
+  DuxtResolvedSource,
+  DuxtSource,
+  DuxtSourcesOptions
+} from './sources-resolve';
+import type {
+  DuxtSectionPage,
+  DuxtSectionType,
+  DuxtSectionTypes
+} from './sections-resolve';
+import {
+  duxtSectionTypes,
+  generatedSectionRef,
+  missingSectionArtefact,
+  resolveGeneratedSections,
+  sectionPages
+} from './sections-resolve';
+import { resolveLatestRefs } from './sources-git';
+import { pageSchema, repositoryRoot } from './sources';
+
+/**
+ * One collection per declared section.
+ *
+ * Composed beside `duxtSources` rather than inside it: both read the same
+ * source list, and keeping them apart is what lets `duxtSources` walk its own
+ * result index-for-index against `expandSources`.
+ */
+export function duxtGeneratedCollections(
+  input: DuxtSource[],
+  options: DuxtSourcesOptions = {},
+  types: DuxtSectionTypes = duxtSectionTypes()
+) {
+  // The same `latest` resolution both other entry points do. Cached per
+  // repository for the life of the process, so asking again is free and cannot
+  // straddle a release.
+  const sources = resolveLatestRefs(input);
+  const collections: Record<string, ReturnType<typeof defineCollection>> = {};
+
+  for (const entry of resolveGeneratedSections(sources, options, types)) {
+    const type = types[entry.generated!.type]!;
+
+    collections[entry.collection] = entry.generated!.remote
+      ? remoteCollection(entry, type)
+      : localCollection(entry, type);
+  }
+
+  return collections;
+}
+
+/**
+ * A section whose artefact is in the repository being built.
+ *
+ * Read and parsed HERE, while the config is being loaded, rather than lazily:
+ * the file is on disk already, and a missing one is an error this build must
+ * fail on — see `missingSectionArtefact`. Failing at config load says which
+ * section and which path, where the same throw from inside the parse pass says
+ * neither.
+ */
+function localCollection(entry: DuxtResolvedSource, type: DuxtSectionType) {
+  const file = join(repositoryRoot(), entry.path);
+
+  const pages = existsSync(file)
+    ? sectionPages(entry, type, readFileSync(file, 'utf8'))
+    : missingSectionArtefact(entry, file);
+
+  const source = defineCollectionSource({
+    getKeys: async () => pages.map((page) => page.file),
+    getItem: async (key) => body(pages, key)
+  });
+
+  // The URL these pages are served at. Content builds a page's path from its
+  // key with the source's prefix in front, which is the whole reason a section
+  // needs no route of its own.
+  source.prefix = entry.prefix;
+
+  return defineCollection({ type: 'page', schema: pageSchema, source });
+}
+
+/**
+ * A section whose artefact is in a repository Content downloads.
+ *
+ * The download is Content's, not this layer's: the collection is declared with
+ * the ordinary `repository` source, and only `getKeys`/`getItem` are replaced.
+ * That is deliberate — where the checkout lands under `.data/content/` is
+ * Content's own hash-cached answer, and a second implementation of it would be
+ * a directory name that drifts on the first release.
+ *
+ * Lazy, because the checkout does not exist until Content has run `prepare`.
+ */
+function remoteCollection(entry: DuxtResolvedSource, type: DuxtSectionType) {
+  const ref = generatedSectionRef(entry);
+  const url = entry.repositoryUrl!;
+
+  const collection = defineCollection({
+    type: 'page',
+    schema: pageSchema,
+    source: {
+      repository: ref
+        ? 'tag' in ref
+          ? { url, tag: ref.tag }
+          : { url, branch: ref.branch }
+        : url,
+      include: entry.path
+    }
+  });
+
+  const source = collection.source![0]!;
+  source.prefix = entry.prefix;
+
+  let pages: DuxtSectionPage[] | undefined;
+
+  const read = () => {
+    if (pages) return pages;
+
+    // `cwd` is where Content put the checkout, filled in by the `prepare` it
+    // installed on this source and run before the first `getKeys`.
+    const file = join(source.cwd, entry.path);
+
+    pages = existsSync(file)
+      ? sectionPages(entry, type, readFileSync(file, 'utf8'))
+      : missingSectionArtefact(entry, file);
+
+    return pages;
+  };
+
+  source.getKeys = async () => read().map((page) => page.file);
+  source.getItem = async (key) => body(read(), key);
+
+  return collection;
+}
+
+/** One page's file, by name. */
+function body(pages: DuxtSectionPage[], key: string): string {
+  return pages.find((page) => page.file === key)?.body ?? '';
+}

package/server/devtools/content.ts

@@ -0,0 +1,120 @@
+import type { H3Event } from 'h3';
+import {
+  queryCollection,
+  queryCollectionSearchSections
+} from '@nuxt/content/nitro';
+import type { Collected, PageRecord } from '../../validate-report';
+import { walk } from '../../validate-report';
+import { context, resolvedSources } from './context';
+import type { Doc, DocGroup, IndexedSection } from './render/content';
+import { renderChecks, renderPages, renderSearch } from './render/content';
+
+/**
+ * The queries behind the three content panels.
+ *
+ * All three ask the running site — `queryCollection` against the database the
+ * pages render from — instead of re-reading Markdown off disk. A panel that
+ * parsed its own copy would answer about a site that does not exist. What comes
+ * back goes to `render/content.ts`, which turns it into the tables.
+ */
+
+async function docsOf(event: H3Event, fields?: string[]): Promise<DocGroup[]> {
+  const sources = resolvedSources();
+
+  return Promise.all(
+    sources.map(async (source) => {
+      try {
+        const query = queryCollection(
+          event,
+          source.collection as Parameters<typeof queryCollection>[1]
+        );
+        const docs = (await (
+          fields ? query.select(...(fields as ['path'])) : query
+        )
+          .order('path', 'ASC')
+          .all()) as unknown as Doc[];
+
+        return { collection: source.collection, docs };
+      } catch {
+        return { collection: source.collection, docs: [] };
+      }
+    })
+  );
+}
+
+/** Every page, with what the frontmatter and the git history gave it. */
+export async function pagesPanel(event: H3Event): Promise<string> {
+  const groups = await docsOf(event, [
+    'path',
+    'title',
+    'description',
+    'icon',
+    'id',
+    'lastUpdated',
+    'contributors'
+  ]);
+
+  return renderPages(groups, context.rootDir);
+}
+
+/** The build validator, run against the served site. */
+export async function checksPanel(event: H3Event): Promise<string> {
+  const sources = resolvedSources();
+  const groups = await docsOf(event);
+
+  const pages: PageRecord[] = groups.flatMap(({ collection, docs }) =>
+    docs.map((doc) => {
+      const collected: Collected = {
+        anchors: new Set<string>(),
+        links: [],
+        commands: []
+      };
+      walk(doc.body, collected);
+
+      return {
+        collection,
+        path: doc.path,
+        file: doc.id ?? doc.path,
+        title: doc.title,
+        description: doc.description,
+        anchors: collected.anchors,
+        links: collected.links,
+        commands: collected.commands
+      };
+    })
+  );
+
+  return renderChecks(sources, pages, context.rootDir);
+}
+
+/** What the search index holds, through the same query the client runs. */
+export async function searchPanel(
+  event: H3Event,
+  term: string
+): Promise<string> {
+  const sources = resolvedSources();
+
+  const sections = (
+    await Promise.all(
+      sources.map(async (source) => {
+        try {
+          const found = await queryCollectionSearchSections(
+            event,
+            source.collection as Parameters<
+              typeof queryCollectionSearchSections
+            >[1]
+          );
+
+          return found.map((section) => ({
+            collection: source.collection,
+            ...section
+          })) as IndexedSection[];
+        } catch {
+          return [] as IndexedSection[];
+        }
+      })
+    )
+  ).flat();
+
+  return renderSearch(term, sections);
+}

package/server/devtools/context.ts

@@ -0,0 +1,38 @@
+// @ts-expect-error virtual module, generated in modules/devtools.ts
+import { devtools } from '#duxt-devtools';
+import type { DevtoolsContext } from './shell';
+
+/**
+ * The two things a panel cannot render itself: where this build sits on disk,
+ * and what the running app config resolved to.
+ *
+ * Split from `shell.ts` so that file stays free of both the virtual module and
+ * the Nitro auto-imports. Everything in `shell.ts` and `render/` is then plain
+ * data in, HTML out — importable from a plain Node script, which is how the
+ * documentation renders a panel of its own with fixture data instead of a
+ * screenshot that goes stale.
+ */
+export const context = devtools as DevtoolsContext;
+
+/** The collections the site is serving, straight out of the running app config. */
+export function resolvedSources(): DuxtResolvedSource[] {
+  const { duxt } = useAppConfig() as { duxt?: Partial<DuxtConfig> };
+
+  return (
+    duxt?.resolvedSources ?? [
+      {
+        collection: 'docs',
+        prefix: '',
+        path: 'docs',
+        isDefault: true,
+        // The fallback is the site's only source, so it is also the language
+        // everything falls back to — the field is not optional on the manifest.
+        isDefaultLocale: true,
+        status: 'current',
+        // A source read off disk is a full checkout, so its history is
+        // readable without asking.
+        history: true
+      }
+    ]
+  );
+}

package/server/devtools/entry-path.ts

@@ -0,0 +1,30 @@
+import { join, resolve } from 'node:path';
+
+/**
+ * Resolve a cache entry the tab may delete, or refuse.
+ *
+ * Its own file, importing nothing but `node:path`, for the same reason
+ * `validate-report.ts` is its own file: everything else under `devtools/`
+ * reaches the virtual module the build generates, and a guard that cannot be
+ * tested without booting Nitro is a guard nobody re-checks. This is the one
+ * destructive thing the panel can do, so it is the one part that is proven.
+ *
+ * The name arrives from a form field, so it is checked rather than trusted: the
+ * result has to be a DIRECT child of the cache directory. A traversal, an
+ * absolute path, a nested path or an empty name all resolve somewhere else,
+ * which is why the comparison is on the resolved parent and never on the string
+ * that was submitted.
+ */
+export function cacheEntryToDrop(
+  dataDir: string,
+  name: unknown
+): string | undefined {
+  if (typeof name !== 'string' || !name || name === '.' || name === '..') {
+    return undefined;
+  }
+
+  const target = resolve(dataDir, name);
+  if (resolve(join(target, '..')) !== resolve(dataDir)) return undefined;
+
+  return target;
+}

package/server/devtools/handler.ts

@@ -0,0 +1,104 @@
+import { rmSync } from 'node:fs';
+import type { H3Event } from 'h3';
+import { context } from './context';
+import { page, PANELS } from './shell';
+import { pathsPanel, sourcesPanel, versionsPanel } from './sources';
+import { checksPanel, pagesPanel, searchPanel } from './content';
+import { cacheEntryToDrop } from './entry-path';
+import { cachePanel, configPanel, i18nPanel, redirectsPanel } from './system';
+
+/**
+ * The devtools tab, as one route with a panel per path segment.
+ *
+ * NOT under `server/routes/`, and that is the point. Nitro scans a layer's
+ * `server/routes/` and registers what it finds — in every build, dev or not —
+ * so a file there is a production route no matter what the module that
+ * "registers" it decides. The tab shipped that way once: `/_duxt/devtools` was
+ * in the production server bundle, serving the resolved configuration, absolute
+ * filesystem paths and a POST that deletes a directory, while
+ * `modules/devtools.ts` returned early believing it had prevented exactly that.
+ * Sitting outside the scanned directory, the handler exists only because the
+ * dev-only module points Nitro at it by path. Everything the panels show is computed per
+ * request out of the RUNNING app config and the served database, not out of a
+ * snapshot taken when the module loaded: the first version froze its data into
+ * a virtual module, and editing `app.config.ts` then left the tab confidently
+ * describing the previous state, which is the one thing a debugging view must
+ * never do.
+ */
+export default defineEventHandler(async (event) => {
+  const slug = ((event.context.params?._ as string | undefined) ?? '').replace(
+    /^\/+|\/+$/g,
+    ''
+  );
+
+  if (slug && !PANELS.some((panel) => panel.slug === slug)) {
+    setResponseStatus(event, 404);
+    return html(page('', '<div class="note">No such panel.</div>'));
+  }
+
+  // The one mutation in the tab: dropping a cache entry. A POST because it
+  // deletes, so a reload or a prefetch cannot trigger it.
+  if (event.method === 'POST' && slug === 'cache') {
+    const body = (await readBody(event)) as { drop?: string } | undefined;
+    const target = cacheEntryToDrop(context.dataDir, body?.drop);
+
+    if (!target) {
+      return html(
+        page(
+          slug,
+          cachePanel('That name is not an entry of the cache directory.')
+        )
+      );
+    }
+
+    rmSync(target, { recursive: true, force: true });
+
+    return html(
+      page(
+        slug,
+        cachePanel(`Dropped ${body?.drop}. The next build re-downloads it.`)
+      )
+    );
+  }
+
+  const query = getQuery(event) as { path?: string; q?: string };
+
+  const body = await panelBody(event, slug, query);
+
+  return html(page(slug, body));
+});
+
+function panelBody(
+  event: H3Event,
+  slug: string,
+  query: { path?: string; q?: string }
+): string | Promise<string> {
+  switch (slug) {
+    case 'paths':
+      return pathsPanel(event, query.path ?? '');
+    case 'pages':
+      return pagesPanel(event);
+    case 'versions':
+      return versionsPanel(event);
+    case 'checks':
+      return checksPanel(event);
+    case 'search':
+      return searchPanel(event, query.q ?? '');
+    case 'config':
+      return configPanel();
+    case 'i18n':
+      return i18nPanel();
+    case 'cache':
+      return cachePanel();
+    case 'redirects':
+      return redirectsPanel();
+    default:
+      return sourcesPanel();
+  }
+}
+
+function html(body: string) {
+  return new Response(body, {
+    headers: { 'content-type': 'text/html; charset=utf-8' }
+  });
+}