@agentvibes/site 0.0.0-stage → 0.10.0

package/src/prepare/files.ts

@@ -0,0 +1,95 @@
+/**
+ * Writing the files `prepare` owns. Every generated file carries the marker,
+ * so a rerun may replace or delete it; a file without the marker belongs to
+ * the author and is never overwritten.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const GENERATED_MARKER = "generated by agentvibes-site prepare";
+const NOTICE = `${GENERATED_MARKER}: do not edit; change site.config.ts or content/ and rerun it.`;
+
+export type CommentStyle = "slash" | "css" | "hash" | "xml";
+
+export function withHeader(style: CommentStyle, body: string): string {
+  const header = {
+    slash: `// ${NOTICE}`,
+    css: `/* ${NOTICE} */`,
+    hash: `# ${NOTICE}`,
+    xml: `<!-- ${NOTICE} -->`
+  }[style];
+  return `${header}\n${body}`;
+}
+
+export type GeneratedFile = {
+  /** Path relative to the site directory, with forward slashes. */
+  readonly path: string;
+  readonly content: string;
+};
+
+export class GeneratedFileConflictError extends Error {
+  override readonly name = "GeneratedFileConflictError";
+}
+
+export function isGenerated(file: string): boolean {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
+  const fd = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(512);
+    const read = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.subarray(0, read).toString("utf8").includes(GENERATED_MARKER);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function walk(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? walk(full) : [full];
+  });
+}
+
+function removeEmptyDirs(dir: string, stop: string): void {
+  let current = dir;
+  while (current.startsWith(stop) && current !== stop && fs.existsSync(current) && fs.readdirSync(current).length === 0) {
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+export type WriteReport = { readonly written: string[]; readonly unchanged: string[]; readonly removed: string[] };
+
+/**
+ * Write `files` under `siteDir`, then delete generated files in `ownedDirs`
+ * (and generated top-level files) that are no longer produced.
+ */
+export function writeGeneratedFiles(siteDir: string, files: readonly GeneratedFile[], ownedDirs: readonly string[]): WriteReport {
+  const report: WriteReport = { written: [], unchanged: [], removed: [] };
+  for (const file of files) {
+    const target = path.join(siteDir, file.path);
+    if (fs.existsSync(target) && !isGenerated(target)) {
+      throw new GeneratedFileConflictError(
+        `${file.path} exists and was not generated by agentvibes-site; move it away (or delete it) so prepare can own it.`
+      );
+    }
+    if (fs.existsSync(target) && fs.readFileSync(target, "utf8") === file.content) {
+      report.unchanged.push(file.path);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content);
+    report.written.push(file.path);
+  }
+  const keep = new Set(files.map((file) => path.join(siteDir, file.path)));
+  const topLevel = fs.readdirSync(siteDir).map((name) => path.join(siteDir, name));
+  const candidates = [...topLevel, ...ownedDirs.flatMap((dir) => walk(path.join(siteDir, dir)))];
+  for (const candidate of candidates) {
+    if (keep.has(candidate) || !isGenerated(candidate)) continue;
+    fs.rmSync(candidate);
+    removeEmptyDirs(path.dirname(candidate), siteDir);
+    report.removed.push(path.relative(siteDir, candidate).split(path.sep).join("/"));
+  }
+  return report;
+}

package/src/prepare/finish-static.ts

@@ -0,0 +1,122 @@
+/**
+ * `agentvibes-site finish-static`: what `next build` cannot do for a static
+ * export, run on `out/` right after it. It moves the Markdown twins next to
+ * their pages (`out/docs/init.md`), and turns the author's `redirects()`, which
+ * Next ignores in an export, into pages that send the visitor on.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { loadSiteConfigFile } from "@agentvibes/site-config/node";
+
+import { ASSETS_DIR, ASSETS_MARKER_FILE } from "./assets";
+import { loadAuthorNextConfig } from "./author-next-config";
+import { findConfig } from "./index";
+
+export class FinishStaticError extends Error {
+  override readonly name = "FinishStaticError";
+}
+
+const MARKDOWN_DIR = "llms.mdx";
+
+export type StaticRedirect = { readonly source: string; readonly destination: string };
+
+function moveInto(from: string, to: string): void {
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const source = path.join(from, entry.name);
+    const target = path.join(to, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(target, { recursive: true });
+      moveInto(source, target);
+    } else {
+      fs.renameSync(source, target);
+    }
+  }
+  fs.rmdirSync(from);
+}
+
+function walkFiles(dir: string): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? walkFiles(full) : [full];
+  });
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** A matcher for the two forms static sites use: `:name` and `:name(a|b)`. Anything else cannot be expanded to files. */
+export function redirectMatcher(source: string): RegExp {
+  const pattern = source.replace(/:([A-Za-z0-9_]+)(\([^)]*\))?|[^:]+/g, (part, name: string | undefined, choices: string | undefined) => {
+    if (name === undefined) {
+      if (/[*+?()]/.test(part)) throw new FinishStaticError(`redirect source ${source}: only :name and :name(a|b) can become static pages`);
+      return escapeRegExp(part);
+    }
+    return `(?<${name}>${choices === undefined ? "[^/]+" : choices.slice(1, -1)})`;
+  });
+  return new RegExp(`^${pattern}$`);
+}
+
+/** The redirects that apply to the exported pages: `/docs/agent/jsdoc` → `/docs/agent/api`. */
+export function expandRedirects(redirects: readonly StaticRedirect[], pagePaths: readonly string[]): StaticRedirect[] {
+  return redirects.flatMap((redirect) => {
+    const matcher = redirectMatcher(redirect.source);
+    return pagePaths.flatMap((page) => {
+      const found = matcher.exec(page);
+      if (found === null) return [];
+      const destination = redirect.destination.replace(/:([A-Za-z0-9_]+)/g, (_all, name: string) => found.groups?.[name] ?? `:${name}`);
+      return [{ source: page, destination }];
+    });
+  });
+}
+
+/** A page whose only job is to send the visitor on: no server can answer 308 on a static host. */
+export function redirectPage(url: string, lang: string): string {
+  const attribute = url.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  return `<!doctype html><html lang="${lang}"><head><meta charset="utf-8"><title>Moved</title><link rel="icon" href="data:,"><meta name="robots" content="noindex"><link rel="canonical" href="${attribute}"><meta http-equiv="refresh" content="0;url=${attribute}"></head><body><a href="${attribute}">Moved here</a></body></html>\n`;
+}
+
+async function authorRedirects(siteDir: string): Promise<StaticRedirect[]> {
+  return (await loadAuthorNextConfig(siteDir)).redirects();
+}
+
+export type FinishReport = {
+  readonly markdownTwins: number;
+  readonly redirects: readonly StaticRedirect[];
+  readonly files: number;
+  readonly bytes: number;
+  readonly largest: { readonly file: string; readonly bytes: number };
+};
+
+export async function finishStatic(siteDir: string, basePath: string): Promise<FinishReport> {
+  const out = path.join(path.resolve(siteDir), "out");
+  if (!fs.existsSync(path.join(out, "index.html"))) throw new FinishStaticError(`${out}/index.html is missing: run next build with static output first`);
+
+  // prepare's bookkeeping in public/_av: not content, and that .gitignore would hide the fonts from whoever commits out/.
+  const assets = path.join(out, path.relative("public", ASSETS_DIR));
+  for (const file of [ASSETS_MARKER_FILE, ".gitignore"]) fs.rmSync(path.join(assets, file), { force: true });
+
+  const twinsDir = path.join(out, MARKDOWN_DIR);
+  const markdownTwins = fs.existsSync(twinsDir) ? walkFiles(twinsDir).length : 0;
+  if (markdownTwins > 0) moveInto(twinsDir, out);
+
+  const pages = walkFiles(out)
+    .filter((file) => path.basename(file) === "index.html")
+    .map((file) => `/${path.relative(out, path.dirname(file)).split(path.sep).join("/")}`.replace(/\/$/, "") || "/");
+  const redirects = expandRedirects(await authorRedirects(siteDir), pages);
+  // The page language comes from site.config; a site with no redirect has no page that needs it.
+  const lang = redirects.length === 0 ? "en" : (await loadSiteConfigFile(findConfig(path.resolve(siteDir)))).config.lang;
+  for (const redirect of redirects) {
+    const dir = path.join(out, redirect.source);
+    // The whole directory: Next's client router would otherwise read the old page's data files instead of redirecting.
+    fs.rmSync(dir, { recursive: true });
+    fs.mkdirSync(dir, { recursive: true });
+    const target = /^[a-z]+:\/\//i.test(redirect.destination) ? redirect.destination : `${basePath}${redirect.destination.replace(/\/?$/, "/")}`;
+    fs.writeFileSync(path.join(dir, "index.html"), redirectPage(target, lang));
+  }
+
+  const sizes = walkFiles(out).map((file) => ({ file: path.relative(out, file), bytes: fs.statSync(file).size }));
+  const largest = sizes.reduce((best, item) => (item.bytes > best.bytes ? item : best), { file: "", bytes: 0 });
+  return { markdownTwins, redirects, files: sizes.length, bytes: sizes.reduce((sum, item) => sum + item.bytes, 0), largest };
+}

package/src/prepare/index.ts

@@ -0,0 +1,291 @@
+/**
+ * `agentvibes-site prepare`: reads site.config.ts, the preset, project.toml,
+ * the npm modules' sources and CHANGELOG.md files, and writes the Next app
+ * (routes, layout, config files, baked data). Run before `next build`/`next dev`.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { warnDegraded } from "@agentvibes/kit/diagnostics";
+import { appColors } from "@agentvibes/site-app";
+import { monogramSvg, renderFavicon } from "@agentvibes/site-app/icons";
+import { unsupportedBecause, type SiteConfig, type SiteTheme } from "@agentvibes/site-config";
+import { findProjectToml, loadSiteConfigFile, loadSitePreset, readProjectToml } from "@agentvibes/site-config/node";
+import { parseTerminalFrame } from "@agentvibes/site-mdx/media";
+import { PACKAGE_FONTS_DIR } from "@agentvibes/site-mdx/node";
+
+import type { GeneratedSiteData, JsdocData, MediaData, VideoEntry } from "../data";
+import { hasChangelog, hasDocs } from "../nav";
+import { resolveOutput, withBasePath, type OutputFlags, type SiteOutput } from "../output";
+import { siteTheme, themeCss } from "../theme";
+import { writeAssets } from "./assets";
+import { readChangelogs } from "./changelog";
+import { isGenerated, writeGeneratedFiles, type WriteReport } from "./files";
+import { extractApi, resolveSourceEntry } from "./jsdoc-extract";
+import { releaseOf } from "./release";
+import { unimplementedConfig } from "./unimplemented";
+import { loadAuthorNextConfig } from "./author-next-config";
+import { AUTHOR_CHROME, AUTHOR_CSS, AUTHOR_ENTRIES, AUTHOR_NEXT_CONFIG, AUTHOR_PROXY, siteFiles } from "./templates";
+
+const CONFIG_NAMES = ["site.config.ts", "site.config.mts", "site.config.mjs", "site.config.js"];
+
+/** Packages of the Site Factory that ship TypeScript sources and so must be compiled by Next. */
+const FACTORY_PACKAGES = [
+  "@agentvibes/site",
+  "@agentvibes/site-app",
+  "@agentvibes/site-config",
+  "@agentvibes/site-llms",
+  "@agentvibes/site-mdx",
+  "@agentvibes/site-seo",
+  "@agentvibes/site-telemetry",
+  "@agentvibes/theme-public"
+];
+
+export class PrepareError extends Error {
+  override readonly name = "PrepareError";
+}
+
+function git(cwd: string, args: readonly string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch (error) {
+    warnDegraded("site.prepare.git", `git ${args.join(" ")} failed in ${cwd}: ${error instanceof Error ? error.message : String(error)}`);
+    return undefined;
+  }
+}
+
+
+export function findConfig(siteDir: string): string {
+  const found = CONFIG_NAMES.map((name) => path.join(siteDir, name)).find((file) => fs.existsSync(file));
+  if (found === undefined) throw new PrepareError(`No site.config.ts in ${siteDir} (looked for ${CONFIG_NAMES.join(", ")}).`);
+  return found;
+}
+
+function collectJsdoc(config: SiteConfig, repoRoot: string): JsdocData {
+  const modules: Record<string, { entry: string | null; items: ReturnType<typeof extractApi> }> = {};
+  for (const mod of config.sections.npm?.modules ?? []) {
+    const entry = resolveSourceEntry(path.resolve(repoRoot, mod.folder.packageDir));
+    if (entry === undefined) {
+      warnDegraded("site.prepare.jsdoc", `${mod.npm.name}: no TypeScript source entry under ${mod.folder.packageDir}; its API page is empty`);
+      modules[mod.id] = { entry: null, items: [] };
+      continue;
+    }
+    modules[mod.id] = { entry: path.relative(repoRoot, entry).split(path.sep).join("/"), items: extractApi(entry) };
+  }
+  return { modules };
+}
+
+/** Real directory of an installed package, found by walking node_modules up from `fromDir`. */
+function packageDir(name: string, fromDir: string): string {
+  let dir = fromDir;
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", ...name.split("/"));
+    if (fs.existsSync(path.join(candidate, "package.json"))) return fs.realpathSync(candidate);
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new PrepareError(`Cannot find the package ${name} from ${fromDir}; is it installed?`);
+    dir = parent;
+  }
+}
+
+function tailwindSources(siteDir: string): string[] {
+  const appDir = path.join(siteDir, "app");
+  const rel = (target: string) => path.relative(appDir, target).split(path.sep).join("/");
+  const site = packageDir("@agentvibes/site", siteDir);
+  const mdx = packageDir("@agentvibes/site-mdx", site);
+  const app = packageDir("@agentvibes/site-app", site);
+  const ui = packageDir("fumadocs-ui", siteDir);
+  return [`${rel(path.join(ui, "dist"))}/**/*.js`, ...[site, mdx, app].map((dir) => `${rel(path.join(dir, "src"))}/**/*.tsx`)];
+}
+
+/**
+ * Writes `.source/` (fumadocs-mdx's typed collections, which `app/_site/runtime.ts`
+ * imports) by running fumadocs-mdx's own generator in the site directory, so
+ * `tsc` works on a clean checkout before the first `next build`.
+ */
+function generateContentCollections(siteDir: string): void {
+  const dir = packageDir("fumadocs-mdx", siteDir);
+  const manifest: unknown = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  const bin = typeof manifest === "object" && manifest !== null && "bin" in manifest && typeof manifest.bin === "string" ? manifest.bin : undefined;
+  if (bin === undefined) throw new PrepareError(`fumadocs-mdx in ${dir} has no "bin" entry; cannot generate .source/`);
+  execFileSync(process.execPath, [path.join(dir, bin)], { cwd: siteDir, stdio: "inherit" });
+}
+
+/** Root-level generated files the repository should not track. */
+function warnUntrackedIgnores(siteDir: string, files: readonly string[]): void {
+  const notIgnored = files.filter((file) => {
+    try {
+      execFileSync("git", ["check-ignore", "-q", file], { cwd: siteDir, stdio: "ignore" });
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  if (notIgnored.length > 0) {
+    warnDegraded("site.prepare.gitignore", `generated files are not git-ignored in ${siteDir}: ${notIgnored.join(", ")}; add them to a .gitignore`);
+  }
+}
+
+/** kind "app": the app's home is the author's `app/page.tsx`, which prepare must not generate or delete. */
+function requireAuthorHome(siteDir: string): void {
+  const home = path.join(siteDir, "app", "page.tsx");
+  if (!fs.existsSync(home) || isGenerated(home)) {
+    throw new PrepareError(`kind "app" needs your own app/page.tsx (the app's home screen) in ${siteDir}; prepare generates the landing page only for kind "docs" and "landing".`);
+  }
+}
+
+/**
+ * Checks `sections.media.tui.frames` at build time: one `*` in the file name,
+ * and every matching file is a frame or a recording.
+ */
+function checkFrames(siteDir: string, glob: string): void {
+  const dir = path.resolve(siteDir, path.dirname(glob));
+  const pattern = path.basename(glob);
+  if (glob.split("*").length !== 2 || !pattern.includes("*")) {
+    throw new PrepareError(`sections.media.tui.frames must have exactly one "*", in the file name (got ${JSON.stringify(glob)})`);
+  }
+  if (!fs.existsSync(dir)) throw new PrepareError(`sections.media.tui.frames: ${dir} does not exist`);
+  const [before = "", after = ""] = pattern.split("*");
+  for (const file of fs.readdirSync(dir).filter((name) => name.startsWith(before) && name.endsWith(after))) {
+    try {
+      parseTerminalFrame(fs.readFileSync(path.join(dir, file), "utf8"));
+    } catch (error) {
+      throw new PrepareError(`sections.media.tui.frames: ${path.join(dir, file)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/** Next's icon file names under `app/`: an author file there is the site's icon, and prepare draws none. */
+const AUTHOR_APP_ICONS = ["icon.svg", "icon.png", "icon.ico", "icon.jpg", "icon.jpeg", "icon.tsx", "icon.ts", "icon.js"];
+const MONOGRAM_FONT = "JetBrainsMono-Bold.woff2";
+
+function authorFile(file: string): boolean {
+  return fs.existsSync(file) && fs.statSync(file).isFile() && !isGenerated(file);
+}
+
+/**
+ * The site's icon, for every kind of site: the SVG app mode uses
+ * (`app.pwa.icon`), else `icon.svg` beside site.config, else the first
+ * letter of the name on the theme's primary colour. `/favicon.ico` is
+ * rendered from the same SVG unless the author serves their own.
+ */
+async function siteIcon(dir: string, config: SiteConfig, theme: SiteTheme): Promise<{ svg: string | undefined; favicon: string | undefined }> {
+  if (AUTHOR_APP_ICONS.some((name) => authorFile(path.join(dir, "app", name)))) return { svg: undefined, favicon: undefined };
+  const file = path.resolve(dir, config.app?.pwa?.icon ?? "icon.svg");
+  const svg = fs.existsSync(file)
+    ? fs.readFileSync(file, "utf8")
+    : monogramSvg({ name: config.name, background: theme.light.primary, foreground: theme.light.primaryForeground, fontFile: path.join(PACKAGE_FONTS_DIR, MONOGRAM_FONT) });
+  const ownFavicon = authorFile(path.join(dir, "app", "favicon.ico")) || fs.existsSync(path.join(dir, "public", "favicon.ico"));
+  return { svg, favicon: ownFavicon ? undefined : (await renderFavicon(Buffer.from(svg))).toString("base64") };
+}
+
+function hasContentFile(dir: string): boolean {
+  if (!fs.existsSync(dir)) return false;
+  return fs.readdirSync(dir, { withFileTypes: true }).some((entry) => (entry.isDirectory() ? hasContentFile(path.join(dir, entry.name)) : /\.mdx?$/.test(entry.name)));
+}
+
+/** kind "landing" builds no /docs route, so pages under content/docs would be left out of the build without a word. */
+function warnLandingDocs(dir: string, config: SiteConfig): void {
+  if (config.kind !== "landing" || !hasContentFile(path.join(dir, "content", "docs"))) return;
+  warnDegraded(
+    "site.prepare.landing-docs",
+    `kind "landing" builds no /docs route, so the pages under content/docs are not built. For a landing page plus docs use kind: "docs" and put the landing page in content/pages/index.mdx.`
+  );
+}
+
+/** What a static host cannot do, rejected here rather than dropped from the site without a word. */
+async function requireStaticSupport(dir: string, config: SiteConfig): Promise<void> {
+  const fix = 'set output: "server" in site.config (and drop --static)';
+  if (fs.existsSync(path.join(dir, AUTHOR_PROXY))) {
+    throw new PrepareError(`${unsupportedBecause("static", "requestGuard")} ${AUTHOR_PROXY} is in ${dir}: remove it or ${fix}.`);
+  }
+  if (hasDocs(config) && !hasContentFile(path.join(dir, "content", "docs"))) {
+    throw new PrepareError(`A static export needs at least one page under content/docs in ${dir}: add one, or set sections: { docs: false } in site.config for a site without docs.`);
+  }
+  if (config.app?.pwa !== undefined) {
+    throw new PrepareError(`${unsupportedBecause("static", "pwa")} Remove app.pwa or ${fix}.`);
+  }
+  if (fs.existsSync(path.join(dir, AUTHOR_NEXT_CONFIG)) && (await (await loadAuthorNextConfig(dir)).headers()).length > 0) {
+    throw new PrepareError(`${unsupportedBecause("static", "responseHeaders")} ${AUTHOR_NEXT_CONFIG} in ${dir} returns headers(): remove them and set the headers at the host, or ${fix}.`);
+  }
+}
+
+/** Plain URLs in the baked media manifest: Next adds the base path to its own links only. */
+function mediaUnder(output: SiteOutput, media: MediaData): MediaData {
+  const entry = (video: VideoEntry): VideoEntry =>
+    Object.fromEntries(Object.entries(video).map(([key, value]) => [key, typeof value === "string" ? withBasePath(output, value) : value])) as VideoEntry;
+  return { videos: Object.fromEntries(Object.entries(media.videos).map(([name, video]) => [name, entry(video)])) };
+}
+
+/** Config the schema accepts and nothing implements fails the build now, not after it has produced a site without the feature. */
+function requireImplemented(config: SiteConfig, configFile: string): void {
+  const problems = unimplementedConfig(config);
+  if (problems.length > 0) throw new PrepareError(`${configFile} declares features this version does not implement:\n- ${problems.join("\n- ")}`);
+}
+
+export type PrepareResult = { readonly siteDir: string; readonly report: WriteReport; readonly migrations: readonly string[] };
+
+/** A ready `SiteOutput` (library callers) or the command-line flags (resolved against site.config's `output`). */
+export async function prepare(siteDir: string, env: Record<string, string | undefined> = process.env, outputOrFlags: SiteOutput | OutputFlags = {}): Promise<PrepareResult> {
+  const dir = path.resolve(siteDir);
+  const configFile = findConfig(dir);
+  const { config, applied } = await loadSiteConfigFile(configFile);
+  requireImplemented(config, configFile);
+  const output = "kind" in outputOrFlags ? outputOrFlags : resolveOutput(config.output, config.siteUrl, outputOrFlags);
+  warnLandingDocs(dir, config);
+  const repoRoot = git(dir, ["rev-parse", "--show-toplevel"]) ?? dir;
+  const tomlFile = findProjectToml(dir);
+  const preset = config.preset === undefined ? undefined : await loadSitePreset(configFile, config.preset);
+  const theme = siteTheme(preset);
+  const changelogDirs = config.sections.changelog?.packages ?? (config.sections.npm?.modules ?? []).map((mod) => mod.folder.packageDir);
+  const authorHome = config.kind === "app";
+  if (output.kind === "static") await requireStaticSupport(dir, config);
+  if (authorHome) requireAuthorHome(dir);
+  const framesGlob = config.sections.media?.tui?.frames;
+  if (framesGlob !== undefined) checkFrames(dir, framesGlob);
+  const pwa = config.app?.pwa;
+  const media = await writeAssets(dir, {
+    icon: pwa === undefined ? undefined : { svgFile: path.resolve(dir, pwa.icon), background: appColors(pwa, theme.light).background },
+    videosDir: config.sections.media?.videos === undefined ? undefined : path.resolve(dir, config.sections.media.videos)
+  });
+  const generated: GeneratedSiteData = {
+    output,
+    release: releaseOf(env, () => git(dir, ["rev-parse", "HEAD"])),
+    projectToml: tomlFile === undefined ? null : readProjectToml(tomlFile),
+    jsdoc: collectJsdoc(config, repoRoot),
+    changelog: hasChangelog(config) ? readChangelogs(repoRoot, changelogDirs) : [],
+    media: mediaUnder(output, media)
+  };
+  const icon = await siteIcon(dir, config, theme);
+  const files = siteFiles({
+    output,
+    indexed: config.index,
+    lang: config.lang,
+    presetPackage: config.preset,
+    generated,
+    themeCss: themeCss(theme),
+    tailwindSources: tailwindSources(dir),
+    transpilePackages: [...FACTORY_PACKAGES, ...(config.preset === undefined ? [] : [config.preset])],
+    docs: hasDocs(config),
+    jsdoc: (config.sections.npm?.modules.length ?? 0) > 0,
+    changelog: hasChangelog(config),
+    icon: icon.svg,
+    favicon: icon.favicon,
+    app: config.app,
+    authorHome,
+    monoFallback: theme.fonts?.mono,
+    framesGlob,
+    authorNextConfig: fs.existsSync(path.join(dir, AUTHOR_NEXT_CONFIG)),
+    authorCss: fs.existsSync(path.join(dir, AUTHOR_CSS)),
+    authorEntries: fs.existsSync(path.join(dir, AUTHOR_ENTRIES)),
+    authorProxy: fs.existsSync(path.join(dir, AUTHOR_PROXY)),
+    authorChrome: fs.existsSync(path.join(dir, AUTHOR_CHROME))
+  });
+  const report = writeGeneratedFiles(dir, files, ["app"]);
+  generateContentCollections(dir);
+  warnUntrackedIgnores(
+    dir,
+    files.filter((file) => !file.path.startsWith("app/")).map((file) => file.path)
+  );
+  return { siteDir: dir, report, migrations: applied.map((step) => `${step.from} → ${step.to}: ${step.notes.join("; ")}`) };
+}