@kirchdev/duxt 0.1.0

package/server/devtools/preview.ts

@@ -0,0 +1,461 @@
+import type { DuxtSource } from '../../sources-resolve';
+import { duxtManifest } from '../../sections-resolve';
+import type { PageRecord } from '../../validate-report';
+import { page, PANELS } from './shell';
+import type { Doc, DocGroup, IndexedSection } from './render/content';
+import { renderChecks, renderPages, renderSearch } from './render/content';
+import { renderPaths, renderSources, renderVersions } from './render/sources';
+import type { RedirectRule } from './render/system';
+import {
+  renderCache,
+  renderConfig,
+  renderI18n,
+  renderRedirects
+} from './render/system';
+
+/**
+ * Every panel, rendered from a site that does not exist.
+ *
+ * The documentation has to show what a panel looks like, and the two obvious
+ * ways are both bad: a screenshot goes stale the day a column is added, and
+ * pointing the reader at the real route only works inside a dev server — the
+ * tab is not registered in a build at all, so a published page would frame a
+ * 404.
+ *
+ * So the panels are rendered here through the SAME functions the tab uses,
+ * over a fixture site. What the reader sees in the documentation is the real
+ * renderer's output; when a panel gains a column, the pictures in the docs
+ * gain it in the same commit, because there are no pictures.
+ *
+ * The fixture is one imagined site, not ten unrelated tables: `acme/sdk` in two
+ * versions and two languages, `acme/cli` in one — which is the smallest shape
+ * that makes every panel say something. A single-source site would render a
+ * Versions tab with nothing in it.
+ */
+
+const SOURCES: DuxtSource[] = [
+  {
+    path: 'docs',
+    repo: 'acme/sdk',
+    refs: [
+      { branch: 'main', label: 'v2' },
+      { tag: 'v1.9.4', label: 'v1.9', status: 'deprecated' }
+    ],
+    locales: ['en', 'de'],
+    history: true,
+    // A generated section, because a fixture without one shows a Sources table
+    // that cannot be told apart from the one this layer had before sections
+    // existed — and a Checks panel that never demonstrates the findings an
+    // artefact produces.
+    generated: [{ type: 'changelog', path: 'CHANGELOG.md', label: 'Releases' }]
+  },
+  { path: 'docs', repo: 'acme/cli' }
+];
+
+const RESOLVED = duxtManifest(SOURCES, { defaultLocale: 'en' });
+
+const ROOT = '/srv/acme-docs';
+
+/** The layer's own config, as this fixture site would have written it. */
+const CONSUMER = {
+  title: 'Acme SDK',
+  version: 'v2.4.0',
+  sources: SOURCES,
+  resolvedSources: RESOLVED,
+  landing: {
+    headline: {
+      en: 'Ship the SDK, not the glue',
+      de: 'Weniger Kleber, mehr SDK'
+    },
+    command: 'npm i @acme/sdk'
+  },
+  footer: { note: '© Acme Inc.' }
+} as unknown as Record<string, unknown>;
+
+/* -------------------------------------------------------------------------- */
+/* The pages the fixture site serves                                          */
+/* -------------------------------------------------------------------------- */
+
+interface PageSeed {
+  path: string;
+  title?: string;
+  german?: string;
+  description?: boolean;
+  icon?: string;
+  file: string;
+  updated?: string;
+  contributors?: number;
+}
+
+const SDK_PAGES: PageSeed[] = [
+  {
+    path: '/',
+    title: 'Acme SDK',
+    german: 'Acme SDK',
+    description: true,
+    icon: 'lucide:book-open-text',
+    file: 'index.md',
+    updated: '2026-02-11',
+    contributors: 6
+  },
+  {
+    path: '/getting-started',
+    title: 'Getting started',
+    german: 'Erste Schritte',
+    description: true,
+    icon: 'lucide:rocket',
+    file: '1.getting-started/index.md',
+    updated: '2026-02-09',
+    contributors: 4
+  },
+  {
+    path: '/getting-started/install',
+    title: 'Install',
+    german: 'Installation',
+    description: true,
+    file: '1.getting-started/1.install.md',
+    updated: '2026-01-28',
+    contributors: 3
+  },
+  {
+    path: '/guides/deploying',
+    title: 'Deploying',
+    german: 'Deployen',
+    description: true,
+    icon: 'lucide:ship',
+    file: '2.guides/1.deploying.md',
+    updated: '2026-02-10',
+    contributors: 2
+  },
+  {
+    path: '/guides/caching',
+    title: 'Caching',
+    description: true,
+    file: '2.guides/2.caching.md',
+    updated: '2026-02-12',
+    contributors: 1
+  },
+  {
+    path: '/reference/client',
+    title: 'Client',
+    german: 'Client',
+    description: true,
+    icon: 'lucide:plug',
+    file: '3.reference/1.client.md',
+    updated: '2026-02-04',
+    contributors: 5
+  },
+  {
+    // The row every Pages panel is opened for: a page that made it into the
+    // build with no frontmatter to speak of.
+    path: '/reference/errors',
+    file: '3.reference/2.errors.md',
+    updated: '2025-12-19',
+    contributors: 1
+  },
+  {
+    path: '/changelog',
+    title: 'Changelog',
+    description: true,
+    icon: 'lucide:history',
+    file: '4.changelog.md',
+    updated: '2026-02-12',
+    contributors: 8
+  }
+];
+
+const CLI_PAGES: PageSeed[] = [
+  {
+    path: '/',
+    title: 'Acme CLI',
+    description: true,
+    icon: 'lucide:terminal',
+    file: 'index.md'
+  },
+  {
+    path: '/getting-started',
+    title: 'Getting started',
+    description: true,
+    file: '1.getting-started.md'
+  },
+  {
+    path: '/commands',
+    title: 'Commands',
+    description: true,
+    icon: 'lucide:list',
+    file: '2.commands/index.md'
+  },
+  {
+    path: '/commands/run',
+    title: 'acme run',
+    description: true,
+    file: '2.commands/1.run.md'
+  }
+];
+
+/**
+ * Which logical page each collection is missing.
+ *
+ * The gaps are the point. A translation lagging two pages behind and a version
+ * that predates a guide are exactly what the Versions matrix exists to show,
+ * and a fixture where every column is a full house would show nothing at all.
+ */
+const MISSING: Record<string, string[]> = {
+  docs_de_sdk: ['/guides/caching', '/changelog'],
+  docs_sdk_v1_9: ['/guides/caching'],
+  docs_de_sdk_v1_9: ['/guides/caching', '/changelog', '/reference/errors']
+};
+
+/**
+ * The pages a changelog becomes: an overview, then one release each.
+ *
+ * Declared beside the docs seeds rather than inside them because they are not
+ * a docs tree — no `description`, no history of their own, and a name this
+ * layer invented rather than one anybody wrote.
+ */
+const RELEASES: { path: string; title: string; file: string }[] = [
+  { path: '', title: 'Releases', file: 'index.md' },
+  { path: '/0.2.0', title: '0.2.0', file: '1.0.2.0.md' },
+  { path: '/0.1.1', title: '0.1.1', file: '2.0.1.1.md' },
+  { path: '/0.1.0', title: '0.1.0', file: '3.0.1.0.md' }
+];
+
+// What reading that CHANGELOG said about it. A near miss rather than a clean
+// read, for the same reason the docs tree has a stale link in it: the panel is
+// documented by what it looks like when something is wrong.
+for (const source of RESOLVED) {
+  if (!source.generated) continue;
+
+  source.generated.report = {
+    pages: RELEASES.length,
+    warnings: [
+      'the heading "1.3 (Feb 2026)" on line 41 reads like a release but does ' +
+        'not parse as one, so it became part of the release above it instead ' +
+        'of a page of its own. A release heading is a version, optionally ' +
+        'followed by a date in parentheses: `## 1.4.0 (2024-02-01)`.'
+    ]
+  };
+}
+
+function docsOf(source: DuxtResolvedSource): Doc[] {
+  if (source.generated) {
+    return RELEASES.map((release) => ({
+      path: `${source.prefix}${release.path}`,
+      title: release.title,
+      id: `${source.collection}/${release.file}`
+    }));
+  }
+
+  const seeds = source.repo === 'cli' ? CLI_PAGES : SDK_PAGES;
+  const skip = new Set(MISSING[source.collection] ?? []);
+  const german = source.locale === 'de';
+
+  return seeds
+    .filter((seed) => !skip.has(seed.path))
+    .map((seed) => ({
+      path: `${source.prefix}${seed.path === '/' ? '' : seed.path}` || '/',
+      title: german ? seed.german : seed.title,
+      description: seed.description
+        ? 'One line, for the card and the OG image.'
+        : undefined,
+      icon: seed.icon,
+      id: `${source.collection}/${german ? 'de/' : ''}${seed.file}`,
+      lastUpdated:
+        source.history && seed.updated
+          ? `${seed.updated}T09:12:00Z`
+          : undefined,
+      contributors: Array.from(
+        { length: seed.contributors ?? 0 },
+        (_, index) => ({
+          name: `Contributor ${index + 1}`
+        })
+      )
+    }));
+}
+
+const GROUPS: DocGroup[] = RESOLVED.map((source) => ({
+  collection: source.collection,
+  docs: docsOf(source)
+}));
+
+const BY_COLLECTION = new Map(
+  GROUPS.map((group) => [group.collection, group.docs.map((doc) => doc.path)])
+);
+
+/**
+ * The same pages as the validator sees them.
+ *
+ * Two deliberate faults, because a Checks panel with nothing in it teaches
+ * nobody what a finding looks like: one link to a page that was renamed, and
+ * one page with no frontmatter.
+ */
+const RECORDS: PageRecord[] = GROUPS.flatMap((group) =>
+  group.docs.map((doc) => ({
+    collection: group.collection,
+    path: doc.path,
+    file: doc.id ?? doc.path,
+    title: doc.title,
+    description: doc.description,
+    anchors: new Set(['install', 'usage']),
+    links:
+      doc.path.endsWith('/getting-started') && group.collection === 'docs_sdk'
+        ? [{ href: '/guides/cacheing' }, { href: '/guides/deploying#install' }]
+        : []
+  }))
+);
+
+const SECTIONS: IndexedSection[] = [
+  {
+    collection: 'docs_sdk',
+    id: 'docs_sdk/1.getting-started/1.install.md#install',
+    title: 'Install',
+    titles: ['Getting started'],
+    content:
+      'Add the package with your package manager of choice. The SDK ships types, so nothing else is needed to get autocompletion in an editor.'
+  },
+  {
+    collection: 'docs_sdk',
+    id: 'docs_sdk/2.guides/1.deploying.md#build-output',
+    title: 'Build output',
+    titles: ['Deploying'],
+    content:
+      'The build writes a single server bundle and a public directory. Both are what a host needs; nothing else in the repository is read at runtime.'
+  },
+  {
+    collection: 'docs_sdk',
+    id: 'docs_sdk/2.guides/2.caching.md#invalidation',
+    title: 'Invalidation',
+    titles: ['Guides', 'Caching'],
+    content:
+      'A cached response is keyed by the request path and the account tier, so a change of plan is visible without a purge.'
+  },
+  {
+    collection: 'docs_de_sdk',
+    id: 'docs_de_sdk/de/1.getting-started/1.install.md#installation',
+    title: 'Installation',
+    titles: ['Erste Schritte'],
+    content:
+      'Das Paket wird mit dem Paketmanager der Wahl hinzugefügt. Typen liegen bei, mehr braucht ein Editor nicht.'
+  },
+  {
+    collection: 'docs_cli',
+    id: 'docs_cli/2.commands/1.run.md#flags',
+    title: 'Flags',
+    titles: ['Commands', 'acme run'],
+    content:
+      'Every flag has a long form. The short forms exist for the three that are typed most often and are listed beside them.'
+  }
+];
+
+const LOCALE_KEYS = [
+  'duxt.nav.open',
+  'duxt.nav.close',
+  'duxt.search.placeholder',
+  'duxt.search.empty',
+  'duxt.toc.title',
+  'duxt.page.edit',
+  'duxt.page.updated',
+  'duxt.version.switch'
+];
+
+const CACHE = [
+  {
+    name: 'github.com-acme-sdk-main',
+    size: 4.6 * 1024 * 1024,
+    modified: new Date('2026-02-12T08:41:00Z')
+  },
+  {
+    name: 'github.com-acme-sdk-v1.9.4',
+    size: 3.9 * 1024 * 1024,
+    modified: new Date('2026-01-30T17:03:00Z')
+  },
+  {
+    name: 'github.com-acme-cli-main',
+    size: 820 * 1024,
+    modified: new Date('2026-02-11T12:20:00Z')
+  }
+];
+
+const REDIRECTS: RedirectRule[] = [
+  {
+    from: '/sdk/guides/deploy',
+    to: '/sdk/guides/deploying',
+    status: 301,
+    mine: true
+  },
+  {
+    from: '/de/sdk/guides/deploy',
+    to: '/de/sdk/guides/deploying',
+    status: 301,
+    mine: true
+  },
+  {
+    from: '/sdk/v1-9/guides/deploy',
+    to: '/sdk/v1-9/guides/deploying',
+    status: 301,
+    mine: true
+  },
+  { from: '/sitemap.xml', to: '/sitemap_index.xml', status: 307, mine: false }
+];
+
+/* -------------------------------------------------------------------------- */
+/* The panels                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/** The body of one panel, rendered from the fixture site. */
+export function previewBody(slug: string): string {
+  switch (slug) {
+    case 'paths':
+      return renderPaths({
+        // A page that v2 has and v1.9 does not: the fallback's own case, and
+        // the reason this panel exists.
+        input: '/de/sdk/v1-9/guides/caching',
+        locales: ['en', 'de'],
+        fallbackLocale: 'en',
+        sources: RESOLVED,
+        found: null,
+        byCollection: BY_COLLECTION
+      });
+    case 'pages':
+      return renderPages(GROUPS, ROOT);
+    case 'versions':
+      return renderVersions(RESOLVED, BY_COLLECTION);
+    case 'checks':
+      return renderChecks(RESOLVED, RECORDS, ROOT);
+    case 'search':
+      return renderSearch('install', SECTIONS);
+    case 'config':
+      return renderConfig(CONSUMER);
+    case 'i18n':
+      return renderI18n({
+        files: [
+          { dir: 'en', keys: LOCALE_KEYS },
+          { dir: 'de', keys: LOCALE_KEYS },
+          { dir: 'fr', keys: LOCALE_KEYS.slice(0, -2) },
+          { dir: 'pt-BR', keys: [...LOCALE_KEYS, 'duxt.page.translate'] }
+        ],
+        locales: ['en', 'de', 'fr', 'pt-BR'],
+        defaultLocale: 'en'
+      });
+    case 'cache':
+      return renderCache({ dataDir: `${ROOT}/.data/content`, entries: CACHE });
+    case 'redirects':
+      return renderRedirects(REDIRECTS);
+    default:
+      return renderSources(RESOLVED, `${ROOT}/app/app.config.ts`);
+  }
+}
+
+/** The file a preview is written to, and the name a docs page asks for. */
+export const previewFile = (slug: string) => `${slug || 'sources'}.html`;
+
+/** Every panel the documentation can embed. */
+export const PREVIEW_TABS = PANELS.map((panel) => ({
+  ...panel,
+  file: previewFile(panel.slug)
+}));
+
+/** One panel as a whole document, without the tab row — see `page`. */
+export function previewPage(slug: string): string {
+  return page(slug, previewBody(slug), true);
+}

package/server/devtools/render/content.ts

@@ -0,0 +1,233 @@
+import type { PageRecord } from '../../../validate-report';
+import { report } from '../../../validate-report';
+import {
+  code,
+  dim,
+  editor,
+  escape,
+  filter,
+  row,
+  stat,
+  stats,
+  table,
+  tag
+} from '../shell';
+
+/**
+ * The three panels that read the content itself, rather than the config.
+ *
+ * All three describe what the RUNNING site holds: the queries in
+ * `../content.ts` ask Content's own database, the same one the pages render
+ * from, and hand the result here. A panel that parsed its own copy of the
+ * Markdown would answer about a site that does not exist.
+ */
+
+export interface Doc {
+  path: string;
+  title?: string;
+  description?: string;
+  icon?: string;
+  id?: string;
+  lastUpdated?: string;
+  contributors?: { name: string }[];
+  body?: unknown;
+}
+
+export interface DocGroup {
+  collection: string;
+  docs: Doc[];
+}
+
+/** Every page, with what the frontmatter and the git history gave it. */
+export function renderPages(groups: DocGroup[], rootDir = ''): string {
+  const total = groups.reduce((sum, group) => sum + group.docs.length, 0);
+  const untitled = groups.reduce(
+    (sum, group) => sum + group.docs.filter((doc) => !doc.title).length,
+    0
+  );
+  const dated = groups.reduce(
+    (sum, group) => sum + group.docs.filter((doc) => doc.lastUpdated).length,
+    0
+  );
+
+  const summary = stats([
+    stat(total, 'pages'),
+    stat(groups.length, 'collections'),
+    stat(dated, 'with history', dated ? '' : 'warn'),
+    stat(untitled, 'without a title', untitled ? 'warn' : 'ok')
+  ]);
+
+  // One block per collection, the first opened: a site with five versions has
+  // five near-identical tables, and all five expanded is a page nobody reads.
+  const sections = groups.map(({ collection, docs }, index) => {
+    const rows = docs.map((doc) =>
+      row([
+        code(doc.path),
+        escape(doc.title) || tag('missing', 'warn'),
+        doc.description ? dim('yes') : tag('missing', 'warn'),
+        doc.icon ? code(doc.icon) : dim('—'),
+        doc.lastUpdated
+          ? escape(doc.lastUpdated.slice(0, 10))
+          : dim('no history'),
+        doc.contributors?.length
+          ? escape(String(doc.contributors.length))
+          : dim('—'),
+        editor(doc.id, doc.id?.split('/').slice(1).join('/'), rootDir)
+      ])
+    );
+
+    return `<details${index === 0 ? ' open' : ''}>
+      <summary>${escape(collection)} <span class="dim">${docs.length} pages</span></summary>
+      ${docs.length > 12 ? filter(`Filter ${collection}`) : ''}
+      ${table(
+        [
+          'Path',
+          'Title',
+          'Description',
+          'Icon',
+          'Last updated',
+          'Contributors',
+          'File'
+        ],
+        rows,
+        'Content produced no pages here. Every URL under this prefix is a 404 — check the source’s `path` and `refs`; the Checks panel reports it as an error.'
+      )}
+    </details>`;
+  });
+
+  return `${summary}${sections.join('')}`;
+}
+
+/**
+ * The build validator, run against the served site.
+ *
+ * Identical checks to `pnpm build`, from `validate-report.ts` — the point is
+ * not a second opinion but a place where the findings stay put. A warning
+ * printed during a build has scrolled away by the time anyone reads it, and
+ * "last updated" on a broken link is exactly when you want the file name.
+ */
+export function renderChecks(
+  sources: DuxtResolvedSource[],
+  pages: PageRecord[],
+  rootDir = ''
+): string {
+  const { errors, warnings, notes } = report(sources, pages);
+
+  const list = (findings: string[], kind: string) =>
+    table(
+      ['', kind === 'error' ? 'Error' : 'Warning'],
+      findings.map((finding) =>
+        row([tag(kind, kind), fileLinked(finding, rootDir)])
+      )
+    );
+
+  const summary = stats([
+    stat(pages.length, 'pages checked'),
+    stat(sources.length, 'collections'),
+    stat(errors.length, 'errors', errors.length ? 'error' : 'ok'),
+    stat(warnings.length, 'warnings', warnings.length ? 'warn' : 'ok')
+  ]);
+
+  // Notes are not findings and must not read like them: a language's coverage
+  // is a state of the site, and putting it in the warnings table would make
+  // every translated site look as though something were wrong with it.
+  //
+  // A note indented by two spaces belongs UNDER the line above it — the report
+  // is one summary per language followed by the files behind the figure, and
+  // HTML collapses that indent to a single space if it is left as text.
+  const coverage = notes.length
+    ? `<h2>Translations</h2><ul class="steps">${notes
+        .map((note) =>
+          note.startsWith('  ')
+            ? `<li class="dim" style="margin-left:1.5rem">${fileLinked(note.trim(), rootDir)}</li>`
+            : `<li><strong>${fileLinked(note, rootDir)}</strong></li>`
+        )
+        .join('')}</ul>`
+    : '';
+
+  return `${summary}${errors.length ? `<h2>Errors</h2>${list(errors, 'error')}` : ''}${
+    warnings.length ? `<h2>Warnings</h2>${list(warnings, 'warn')}` : ''
+  }${coverage}`;
+}
+
+/**
+ * Findings name their file in quotes; turn the first one into an editor link.
+ *
+ * The message stays exactly the string the build prints — the two must not
+ * drift — so the link is added by reading it rather than by threading a second
+ * field through the report.
+ */
+function fileLinked(finding: string, rootDir: string): string {
+  const match = /"([^"]+\.md)"/.exec(finding);
+  if (!match) return escape(finding);
+
+  const [quoted, file] = match;
+
+  return (
+    escape(finding.slice(0, match.index)) +
+    editor(file, quoted, rootDir) +
+    escape(finding.slice(match.index + quoted.length))
+  );
+}
+
+export interface IndexedSection {
+  collection: string;
+  id: string;
+  title?: string;
+  titles?: string[];
+  content?: string;
+}
+
+/**
+ * What the search index holds.
+ *
+ * The search had three separate bugs — a filter fighting a filter, results that
+ * were heading fragments, table cells run together without separators — and all
+ * three were invisible because nobody could see the sections the index is built
+ * from. This is that list, with the same query the client runs.
+ */
+export function renderSearch(term: string, sections: IndexedSection[]): string {
+  const form = `<form method="get">
+    <input type="search" name="q" value="${escape(term)}" placeholder="A word as a reader would type it" autofocus>
+    <button type="submit">Search</button>
+  </form>`;
+
+  const needle = term.trim().toLowerCase();
+
+  const matching = needle
+    ? sections.filter(
+        (section) =>
+          section.title?.toLowerCase().includes(needle) ||
+          section.content?.toLowerCase().includes(needle)
+      )
+    : sections;
+
+  // The id is the longest string in the table and the least worth reading in
+  // full, so it is the one that gets clipped — otherwise it takes the width the
+  // indexed text needs, and the column that answers the question is a sliver.
+  const rows = matching.slice(0, 200).map(
+    (section) => `<tr>
+      <td>${code(section.collection)}</td>
+      <td><code class="trunc" title="${escape(section.id)}">${escape(section.id)}</code></td>
+      <td>${escape(section.title)}</td>
+      <td>${escape((section.titles ?? []).join(' › ')) || dim('—')}</td>
+      <td class="wide">${escape((section.content ?? '').slice(0, 180))}${(section.content ?? '').length > 180 ? dim(' …') : ''}</td>
+    </tr>`
+  );
+
+  const summary = stats([
+    stat(sections.length, 'sections indexed'),
+    needle
+      ? stat(matching.length, 'matching', matching.length ? '' : 'warn')
+      : undefined,
+    matching.length > 200 ? stat(200, 'shown', 'warn') : undefined
+  ]);
+
+  return `${form}${summary}<div class="note">One row per heading — which is what the dialog groups back into pages. The text column is exactly what FTS5 matches against.</div>${table(
+    ['Collection', 'Id', 'Heading', 'Under', 'Indexed text'],
+    rows,
+    needle
+      ? `Nothing in the index matches “${escape(term)}”. FTS5 matches terms and prefixes, so a typo returns nothing.`
+      : 'The index is empty.'
+  )}`;
+}