@agentvibes/site 0.0.0-stage → 0.10.0

package/src/proxy.ts

@@ -0,0 +1,57 @@
+/**
+ * The Next 16 proxy (formerly middleware) of a Site Factory site:
+ * - `X-Robots-Tag: noindex, nofollow` on every response that may not be indexed;
+ * - `<path>.md` and `Accept: text/markdown` → the page's Markdown, `Vary: Accept` on pages;
+ * - the site's own `site.proxy.ts` guard, if it has one, runs first (a login gate).
+ */
+import type { SiteConfig } from "@agentvibes/site-config";
+import { pagePathOfMarkdown, prefersMarkdown } from "@agentvibes/site-llms";
+import { decideIndexing, indexingHeaders, readDeploymentEnv } from "@agentvibes/site-seo";
+import { NextResponse, type NextRequest } from "next/server";
+
+const NON_PAGE_PREFIXES = ["/_next", "/api/", "/_a/", "/_e", "/og", "/llms.mdx"];
+
+/** A path that renders an HTML page (no file extension, not an internal route). */
+export function isPagePath(path: string): boolean {
+  if (NON_PAGE_PREFIXES.some((prefix) => path === prefix || path.startsWith(prefix))) return false;
+  const last = path.split("/").pop() ?? "";
+  return !last.includes(".");
+}
+
+/** Where a request for Markdown is rewritten to, or undefined when it is not one. */
+export function markdownRewrite(path: string, wantsMarkdown: boolean): string | undefined {
+  const fromExtension = pagePathOfMarkdown(path);
+  const page = fromExtension ?? (wantsMarkdown && isPagePath(path) ? path : undefined);
+  if (page === undefined) return undefined;
+  const normalized = page.replace(/\/+$/, "");
+  return normalized === "" ? "/llms.mdx/index" : `/llms.mdx${normalized}`;
+}
+
+/**
+ * The default export of the optional author file `site.proxy.ts`. It sees every
+ * request the proxy sees, including `/llms.txt`, `<path>.md`, `/api/search` and
+ * `/og`. Return a response to answer the request (a redirect to a login page) or
+ * undefined to let it through.
+ */
+export type SiteGuard = (request: NextRequest) => NextResponse | undefined;
+
+export function createProxy(config: Pick<SiteConfig, "index" | "siteUrl">, guard?: SiteGuard) {
+  return function proxy(request: NextRequest): NextResponse {
+    const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? undefined;
+    const decision = decideIndexing({ index: config.index, siteUrl: config.siteUrl, env: readDeploymentEnv(process.env), host });
+    const headers = indexingHeaders(decision);
+    const answered = guard?.(request);
+    if (answered !== undefined) {
+      for (const [name, value] of Object.entries(headers)) answered.headers.set(name, value);
+      return answered;
+    }
+    const path = request.nextUrl.pathname;
+    const target = markdownRewrite(path, prefersMarkdown(request));
+    const response = target === undefined ? NextResponse.next() : NextResponse.rewrite(new URL(target, request.url));
+    for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+    if (target !== undefined || isPagePath(path)) response.headers.append("Vary", "Accept");
+    return response;
+  };
+}
+
+export { loadConfig } from "./config";

package/src/routes.ts

@@ -0,0 +1,158 @@
+/**
+ * Route handlers. Each takes the site runtime and returns the Next handler;
+ * the generated `app/**\/route.ts` files only bind them.
+ */
+import { llmsTxt, markdownResponse, pageMarkdown, plainTextResponse, VARY_ACCEPT } from "@agentvibes/site-llms";
+import { indexingHeaders, robotsTxt, sitemapXml } from "@agentvibes/site-seo";
+import { createSearchAPI, type AdvancedIndex } from "fumadocs-core/search/server";
+import { match } from "ts-pattern";
+
+import { catalog, catalogSections, findPage } from "./catalog";
+import { requestContextOf, type RequestContext } from "./context";
+import { pathFromStaticSlug, staticSlugOf } from "./output";
+import type { SiteRuntime, SiteSource } from "./runtime";
+
+type SlugContext = { params: Promise<{ slug?: string[] }> };
+type PathContext = { params: Promise<{ path: string[] }> };
+
+function notFoundResponse(headers: Record<string, string>): Response {
+  return new Response("Not found", { status: 404, headers: { "content-type": "text/plain; charset=utf-8", ...headers } });
+}
+
+/**
+ * Whether the sitemap and llms.txt exist. On a server they follow the request's
+ * host. A static build only generates these routes when `index` is not false:
+ * a copy on another host keeps the files of its source, listing canonical
+ * URLs, while its pages and robots.txt stay noindex.
+ */
+function listsPages(site: SiteRuntime, ctx: RequestContext): boolean {
+  return ctx.decision.kind === "index" || site.generated.output.kind === "static";
+}
+
+/** `/robots.txt`: `Disallow: /` unless the request is indexable. */
+export function createRobotsRoute(site: SiteRuntime) {
+  return function GET(request: Request): Response {
+    const ctx = requestContextOf(site, request);
+    return plainTextResponse(robotsTxt(ctx.decision, site.config.siteUrl), indexingHeaders(ctx.decision));
+  };
+}
+
+/** `/sitemap.xml`: canonical URLs of every page; 404 when not indexable. */
+export function createSitemapRoute(site: SiteRuntime) {
+  return function GET(request: Request): Response {
+    const ctx = requestContextOf(site, request);
+    if (!listsPages(site, ctx)) return notFoundResponse(indexingHeaders(ctx.decision));
+    return new Response(sitemapXml(site.config.siteUrl, catalog(site).map((page) => ({ path: page.path }))), {
+      headers: { "content-type": "application/xml; charset=utf-8" }
+    });
+  };
+}
+
+async function llmsBody(site: SiteRuntime): Promise<string> {
+  const generated = llmsTxt(site.seo, catalogSections(site));
+  const extra = (await site.entries?.llms?.())?.trim() ?? "";
+  return extra === "" ? generated : `${generated.trimEnd()}\n\n${extra}\n`;
+}
+
+/**
+ * `/llms.txt`: one section per site section, then the site's own text
+ * (`site.entries.ts`); 404 when not indexable (spec §4: no llms.txt).
+ */
+export function createLlmsRoute(site: SiteRuntime) {
+  return async function GET(request: Request): Promise<Response> {
+    const ctx = requestContextOf(site, request);
+    if (!listsPages(site, ctx)) return notFoundResponse(indexingHeaders(ctx.decision));
+    return plainTextResponse(await llmsBody(site));
+  };
+}
+
+/** `/llms.mdx/<path>`: the Markdown twin of a page (the proxy maps `<path>.md` and `Accept: text/markdown` here). */
+export function createMarkdownRoute(site: SiteRuntime) {
+  return async function GET(request: Request, context: SlugContext): Promise<Response> {
+    const ctx = requestContextOf(site, request);
+    const { slug = [] } = await context.params;
+    const path = site.generated.output.kind === "static" ? pathFromStaticSlug(slug, ".md") : slug.length === 1 && slug[0] === "index" ? "/" : `/${slug.join("/")}`;
+    const page = findPage(site, path);
+    const headers = { ...indexingHeaders(ctx.decision), ...VARY_ACCEPT };
+    if (page === undefined) return notFoundResponse(headers);
+    const text = pageMarkdown({ title: page.title, description: page.description, url: new URL(page.path, site.config.siteUrl).href, body: await page.markdown() });
+    return markdownResponse(text, headers);
+  };
+}
+
+/** Static output: one `.md` file per page; `finish-static` moves them next to their pages. */
+export function createMarkdownParams(site: SiteRuntime) {
+  return () => catalog(site).map((page) => ({ slug: staticSlugOf(page.path, ".md") }));
+}
+
+function contentIndexes(source: SiteSource): AdvancedIndex[] {
+  return source.getPages().map((page) => {
+    const index: AdvancedIndex = { id: page.url, title: page.data.title ?? page.url, url: page.url, structuredData: page.data.structuredData };
+    return page.data.description === undefined ? index : { ...index, description: page.data.description };
+  });
+}
+
+function jsdocIndexes(site: SiteRuntime): AdvancedIndex[] {
+  return (site.config.sections.npm?.modules ?? []).flatMap((mod) => {
+    const items = site.generated.jsdoc.modules[mod.id]?.items ?? [];
+    if (items.length === 0) return [];
+    return [
+      {
+        id: `/docs/${mod.id}/jsdoc`,
+        title: `${mod.title} API reference`,
+        url: `/docs/${mod.id}/jsdoc`,
+        structuredData: {
+          headings: items.map((item) => ({ id: item.name, content: item.name })),
+          contents: items.map((item) => ({
+            heading: item.name,
+            content: [item.description, item.signature, ...(item.members ?? []).map((member) => member.signature)].filter((part) => part !== undefined).join(" ")
+          }))
+        }
+      }
+    ];
+  });
+}
+
+/** `/api/search`: Fumadocs' advanced search over docs, pages, the API references and the site's own entries (`site.entries.ts`). */
+export function createSearchRoute(site: SiteRuntime) {
+  return createSearchAPI("advanced", {
+    indexes: async () => [
+      ...contentIndexes(site.pages),
+      ...(site.config.kind === "landing" ? [] : contentIndexes(site.docs)),
+      ...jsdocIndexes(site),
+      ...((await site.entries?.search?.()) ?? [])
+    ]
+  });
+}
+
+/**
+ * `/favicon.ico`, rendered by prepare from the site's icon and baked into
+ * the route file (Vercel functions do not carry `public/`).
+ */
+export function createFaviconRoute(base64: string) {
+  const bytes = Buffer.from(base64, "base64");
+  return function GET(): Response {
+    return new Response(bytes, { headers: { "content-type": "image/x-icon", "cache-control": "public, max-age=86400" } });
+  };
+}
+
+/** `/_a/<path>`: first-party analytics tunnel; 404 unless analytics is on for this request. */
+export function createAnalyticsTunnel(site: SiteRuntime) {
+  return async function handler(request: Request, context: PathContext): Promise<Response> {
+    const ctx = requestContextOf(site, request);
+    const provider = site.analytics;
+    if (provider === undefined || ctx.telemetry.analytics.kind === "off") return notFoundResponse({});
+    const { path } = await context.params;
+    return provider.tunnel(request, path.join("/"));
+  };
+}
+
+/** `/_e`: first-party error tunnel; 404 unless error capture is on for this request. */
+export function createErrorsTunnel(site: SiteRuntime) {
+  return async function POST(request: Request): Promise<Response> {
+    const ctx = requestContextOf(site, request);
+    const reporter = site.errors;
+    if (reporter === undefined || ctx.telemetry.errors.kind === "off") return notFoundResponse({});
+    return reporter.tunnel(request);
+  };
+}

package/src/runtime.tsx

@@ -0,0 +1,165 @@
+/**
+ * The site runtime: everything a route needs, built once per server from
+ * site.config, the preset, the Fumadocs collections and the data baked by
+ * `prepare`. The generated `app/_site/runtime.ts` calls `createSiteRuntime`.
+ */
+import { resolveTelemetryKeys, type SiteConfig, type SitePreset, type TelemetryKeys } from "@agentvibes/site-config";
+import type { SeoSite } from "@agentvibes/site-seo";
+import { sentryErrorReporter, umamiAnalytics, type AnalyticsProvider, type ErrorReporter, type TelemetryTransport } from "@agentvibes/site-telemetry";
+import type { Root } from "fumadocs-core/page-tree";
+import type { LoaderOutput, MetaData, PageData } from "fumadocs-core/source";
+import { createRelativeLink } from "fumadocs-ui/mdx";
+import type { StructuredData } from "fumadocs-core/mdx-plugins";
+import type { AdvancedIndex } from "fumadocs-core/search/server";
+import type { TOCItemType } from "fumadocs-core/toc";
+import type { MDXComponents } from "mdx/types";
+import type { ComponentProps, ComponentType, FC, ReactNode } from "react";
+import { match } from "ts-pattern";
+
+import type { GeneratedSiteData } from "./data";
+
+/** What a page of a Fumadocs-MDX collection carries (with `includeProcessedMarkdown`). */
+export type SitePageData = PageData & {
+  readonly body: ComponentType<{ components?: MDXComponents }>;
+  readonly toc: TOCItemType[];
+  readonly structuredData: StructuredData;
+  readonly full?: boolean | undefined;
+  getText(type: "raw" | "processed"): Promise<string>;
+};
+
+export type SitePage = {
+  readonly url: string;
+  readonly slugs: readonly string[];
+  readonly data: SitePageData;
+};
+
+/**
+ * The part of a Fumadocs loader the renderer uses. Fumadocs' own
+ * `LoaderOutput` is invariant in its page type, so the runtime adapts each
+ * loader to this shape once instead of carrying the generated types around.
+ */
+export type SiteSource = {
+  readonly pageTree: Root;
+  getPage(slugs: readonly string[]): SitePage | undefined;
+  getPages(): SitePage[];
+  /** The MDX `a` of `page`: resolves relative file links (`./other.mdx`) to page URLs. */
+  relativeLink(page: SitePage): FC<ComponentProps<"a">>;
+};
+
+function PlainLink(props: ComponentProps<"a">) {
+  return <a {...props} />;
+}
+
+/** Adapt a Fumadocs loader (any page type that carries the fields the renderer reads). */
+export function siteSource<P extends SitePageData, M extends MetaData>(loader: LoaderOutput<{ source: { pageData: P; metaData: M }; i18n: undefined }>): SiteSource {
+  return {
+    pageTree: loader.getPageTree(),
+    getPage: (slugs) => loader.getPage([...slugs]),
+    getPages: () => loader.getPages(),
+    relativeLink: (page) => {
+      const original = loader.getPage([...page.slugs]);
+      return original === undefined ? PlainLink : createRelativeLink(loader, original);
+    }
+  };
+}
+
+export type SiteRuntimeInput = {
+  readonly config: SiteConfig;
+  readonly preset: SitePreset | undefined;
+  readonly generated: GeneratedSiteData;
+  /** `content/docs`, served under `/docs`. */
+  readonly docs: SiteSource;
+  /** `content/pages`, served from `/` (the landing page is `content/pages/index.mdx`). */
+  readonly pages: SiteSource;
+  /** The site's own search documents and llms.txt text, from its `site.entries.ts`. */
+  readonly entries?: SiteEntries | undefined;
+  /** The site's own header title, footer and theme storage key, from its `site.chrome.tsx`. */
+  readonly chrome?: SiteChrome | undefined;
+};
+
+/**
+ * What a site replaces in the generated chrome, on every page including the
+ * docs. Default export of the site's optional `site.chrome.tsx`; each field left
+ * out keeps the generated default.
+ */
+export type SiteChrome = {
+  /** Shown in the header instead of `config.name`. */
+  readonly navTitle?: ReactNode;
+  /** Shown instead of the generated footer. */
+  readonly footer?: ReactNode;
+  /** localStorage key of the visitor's theme choice, to keep a choice saved before the move to the generator. */
+  readonly themeStorageKey?: string;
+};
+
+/** Typed identity for `site.chrome.tsx`: `export default defineSiteChrome({ navTitle, footer })`. */
+export function defineSiteChrome(chrome: SiteChrome): SiteChrome {
+  return chrome;
+}
+
+/** A search document: what Fumadocs' advanced search indexes (title, URL, headings and their text). */
+export type SiteSearchEntry = AdvancedIndex;
+
+/**
+ * What a site adds to the generated `/api/search` and `/llms.txt`, for
+ * content that is not an MDX page (a gallery, a catalogue, app screens).
+ * Default export of the site's optional `site.entries.ts`; the generated
+ * routes still decide indexing, so a noindex request gets no llms.txt.
+ */
+export type SiteEntries = {
+  /** Documents searched besides the pages, the docs and the API references. */
+  readonly search?: () => readonly SiteSearchEntry[] | Promise<readonly SiteSearchEntry[]>;
+  /** Markdown appended to llms.txt after the generated sections (start it with a `## ` heading). */
+  readonly llms?: () => string | Promise<string>;
+};
+
+/** Typed identity for `site.entries.ts`: `export default defineSiteEntries({ search, llms })`. */
+export function defineSiteEntries(entries: SiteEntries): SiteEntries {
+  return entries;
+}
+
+export type SiteRuntime = SiteRuntimeInput & {
+  readonly seo: SeoSite;
+  readonly telemetryKeys: TelemetryKeys;
+  readonly analytics: AnalyticsProvider | undefined;
+  readonly errors: ErrorReporter | undefined;
+};
+
+/** A static host has no tunnels to post to, so the browser talks to the collector itself. */
+export function telemetryTransport(site: SiteRuntime): TelemetryTransport {
+  return site.generated.output.kind === "static" ? "direct" : "tunnel";
+}
+
+export class SiteTelemetryConfigError extends Error {
+  override readonly name = "SiteTelemetryConfigError";
+}
+
+function analyticsProvider(keys: TelemetryKeys): AnalyticsProvider | undefined {
+  return match(keys.umami)
+    .with({ kind: "configured" }, (umami) => umamiAnalytics({ websiteId: umami.websiteId, host: umami.host }))
+    .with({ kind: "absent" }, () => undefined)
+    .with({ kind: "missing-host" }, (umami) => {
+      throw new SiteTelemetryConfigError(
+        `The Umami website id (from ${umami.source}) has no collector host: set telemetry.umamiHost in site.config, umamiHost in [telemetry] of .agentvibes/project.toml, or use a preset that names one.`
+      );
+    })
+    .exhaustive();
+}
+
+function errorReporter(keys: TelemetryKeys): ErrorReporter | undefined {
+  return match(keys.glitchtip)
+    .with({ kind: "configured" }, (glitchtip) => sentryErrorReporter({ dsn: glitchtip.dsn }))
+    .with({ kind: "absent" }, () => undefined)
+    .exhaustive();
+}
+
+export function createSiteRuntime(input: SiteRuntimeInput): SiteRuntime {
+  // process.env: AGENTVIBES_GLITCHTIP_DSN overrides the configured DSN (site doctor points it at its capture sink).
+  const telemetryKeys = resolveTelemetryKeys(input.config, input.generated.projectToml ?? undefined, input.preset, process.env);
+  return {
+    ...input,
+    seo: { name: input.config.name, description: input.config.description, siteUrl: input.config.siteUrl },
+    telemetryKeys,
+    analytics: analyticsProvider(telemetryKeys),
+    errors: errorReporter(telemetryKeys)
+  };
+}

package/src/theme.ts

@@ -0,0 +1,59 @@
+import type { SitePreset, SiteTheme, ThemeColors } from "@agentvibes/site-config";
+import { publicTheme } from "@agentvibes/theme-public";
+
+const VARIABLES: ReadonlyArray<readonly [keyof ThemeColors, string]> = [
+  ["background", "--color-fd-background"],
+  ["foreground", "--color-fd-foreground"],
+  ["muted", "--color-fd-muted"],
+  ["mutedForeground", "--color-fd-muted-foreground"],
+  ["popover", "--color-fd-popover"],
+  ["popoverForeground", "--color-fd-popover-foreground"],
+  ["card", "--color-fd-card"],
+  ["cardForeground", "--color-fd-card-foreground"],
+  ["border", "--color-fd-border"],
+  ["primary", "--color-fd-primary"],
+  ["primaryForeground", "--color-fd-primary-foreground"],
+  ["secondary", "--color-fd-secondary"],
+  ["secondaryForeground", "--color-fd-secondary-foreground"],
+  ["accent", "--color-fd-accent"],
+  ["accentForeground", "--color-fd-accent-foreground"],
+  ["ring", "--color-fd-ring"],
+  ["info", "--color-fd-info"],
+  ["warning", "--color-fd-warning"],
+  ["error", "--color-fd-error"],
+  ["success", "--color-fd-success"]
+];
+
+function declarations(colors: ThemeColors): string {
+  return VARIABLES.map(([key, variable]) => `  ${variable}: ${colors[key]};`).join("\n");
+}
+
+/**
+ * CSS that maps the site theme ({@link siteTheme}) onto Fumadocs'
+ * `--color-fd-*` variables. The light palette applies to `:root:not(.dark)`;
+ * a theme without a dark palette leaves Fumadocs' neutral
+ * `.dark` one in place for dark mode.
+ */
+export function themeCss(theme: SiteTheme): string {
+  const blocks = [`/* theme: ${theme.name} */`, `:root:not(.dark) {\n${declarations(theme.light)}\n}`];
+  if (theme.dark !== undefined) blocks.push(`.dark {\n${declarations(theme.dark)}\n}`);
+  const extras: string[] = [];
+  if (theme.fonts !== undefined) extras.push(`  --font-sans: ${theme.fonts.sans};`, `  --font-mono: ${theme.fonts.mono};`);
+  if (theme.radius !== undefined) extras.push(`  --radius: ${theme.radius};`);
+  if (extras.length > 0) blocks.push(`:root {\n${extras.join("\n")}\n}`);
+  return `${blocks.join("\n\n")}\n`;
+}
+
+/** Colours for generated images (OG): the light palette of the site theme. */
+export function ogColors(theme: SiteTheme): { background: string; foreground: string; muted: string; accent: string } {
+  return { background: theme.light.background, foreground: theme.light.foreground, muted: theme.light.mutedForeground, accent: theme.light.primary };
+}
+
+/**
+ * The theme a site is drawn with: its preset's, else the public theme
+ * (`@agentvibes/theme-public`, light and dark), so a site without a preset gets
+ * the public defaults (spec §3) rather than Fumadocs' bare neutral.
+ */
+export function siteTheme(preset: SitePreset | undefined): SiteTheme {
+  return preset?.theme ?? publicTheme;
+}