@dogsbay/format-astro 0.2.0-beta.0

package/dist/plugins.js

@@ -0,0 +1,339 @@
+/**
+ * Plugin-runtime codegen — the format-astro side of the plugin API.
+ *
+ * Each Dogsbay site build emits a fresh set of plugin-runtime
+ * source files in the generated Astro project so plugins'
+ * client-side code, virtual config modules, and stylesheets
+ * participate in the user's Astro / Vite / Tailwind build.
+ *
+ * The emitters are intentionally idempotent: running a build twice
+ * with the same plugin set produces the same output. When a plugin
+ * is removed from config, the next build leaves orphan files
+ * untouched (cheap; format-astro never deletes user-modifiable
+ * files); the orphans are inert because no `import` references
+ * them. A `pnpm clean` clears them.
+ *
+ * Files written:
+ *
+ *   src/lib/plugin-runtime.ts
+ *     The single entry point DocsLayout's <script> imports. Each
+ *     plugin's clientModules paths get an `import "..."` line in
+ *     declaration order.
+ *
+ *   src/lib/plugin-config/<id>.ts
+ *     One per plugin that called `defineClientConfig`. Exports the
+ *     value as `default` so client modules can do
+ *     `import config from "virtual:dogsbay-plugin-config/<id>"`.
+ *
+ *   src/styles/plugins/<id>.css
+ *     Copy of each plugin's `styles()` files. Imported into
+ *     `src/styles/global.css` via an injected block delimited by
+ *     marker comments — re-runs replace just that block.
+ *
+ *   astro.config.plugins.mjs
+ *     Module that exports a Vite alias map keyed by virtual config
+ *     name. astro.config.mjs imports + spreads it; the alias map
+ *     is tiny (one entry per plugin with defineClientConfig).
+ *
+ * See plans/plugin-api.md.
+ */
+import { writeFileSync, readFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from "node:fs";
+import { dirname, join, basename, extname } from "node:path";
+/**
+ * Slots the runtime emits stack files for. Each entry is always
+ * emitted (even when no plugin contributes) so per-page emission
+ * can unconditionally import + use the stack. Adding a new slot
+ * requires both an entry here and a usage site in format-astro's
+ * page emitter.
+ */
+const KNOWN_SLOTS = ["MarkdownContent"];
+const PLUGIN_RUNTIME_REL = "src/lib/plugin-runtime.ts";
+const PLUGIN_CONFIG_DIR_REL = "src/lib/plugin-config";
+const PLUGIN_STYLES_DIR_REL = "src/styles/plugins";
+const PLUGIN_WRAPPERS_DIR_REL = "src/components/wrappers";
+const PLUGIN_VITE_REL = "astro.config.plugins.mjs";
+const GLOBAL_CSS_REL = "src/styles/global.css";
+const GLOBAL_CSS_BEGIN = "/* dogsbay:plugins:begin */";
+const GLOBAL_CSS_END = "/* dogsbay:plugins:end */";
+/**
+ * Emit the plugin-runtime artefacts. Safe to call when there are
+ * no plugins — every emitted file is shaped to compile and behave
+ * as a no-op when no plugin contributes that surface.
+ */
+export function emitPluginRuntime(options) {
+    emitClientModulesEntry(options);
+    emitClientConfigModules(options);
+    emitPluginStyles(options);
+    emitPluginViteAliases(options);
+    emitWrapperStacks(options);
+}
+/**
+ * Write `src/lib/plugin-runtime.ts` — the single entry point
+ * DocsLayout pulls in. One import per client-module path, in
+ * plugin declaration order.
+ */
+function emitClientModulesEntry(options) {
+    const lines = [
+        "// Auto-generated by dogsbay site build. Do not edit by hand.",
+        "// One import per plugin client module, in declaration order.",
+        "// See plans/plugin-api.md → \"Build pipeline integration\".",
+        "",
+    ];
+    for (const { pluginId, paths } of options.clientModules) {
+        lines.push(`// ${pluginId}`);
+        for (const p of paths) {
+            // Convert absolute paths to a Vite-friendly URL form. Astro
+            // can resolve absolute fs paths via Vite's `/@fs/` prefix in
+            // dev, and at build time Vite/rollup follow them directly.
+            lines.push(`import ${JSON.stringify(p)};`);
+        }
+    }
+    if (options.clientModules.length === 0) {
+        lines.push("// No plugin client modules registered.");
+    }
+    lines.push("");
+    writeFile(join(options.outputDir, PLUGIN_RUNTIME_REL), lines.join("\n"));
+}
+/**
+ * Write one TypeScript file per plugin that called
+ * `defineClientConfig`. Each file `export default` the JSON-
+ * serialized value so client modules import a typed default.
+ */
+function emitClientConfigModules(options) {
+    const dir = join(options.outputDir, PLUGIN_CONFIG_DIR_REL);
+    if (options.clientConfigs.length === 0) {
+        // Nothing to emit; leave the dir alone if it exists from prior
+        // builds (idempotency rule above).
+        return;
+    }
+    mkdirSync(dir, { recursive: true });
+    for (const { pluginId, value } of options.clientConfigs) {
+        const fileName = `${slugifyPluginId(pluginId)}.ts`;
+        const safeJson = JSON.stringify(value, null, 2);
+        const contents = [
+            `// Auto-generated config for plugin "${pluginId}".`,
+            `// Imported by client modules via`,
+            `//   virtual:dogsbay-plugin-config/${pluginId}`,
+            "",
+            `export default ${safeJson};`,
+            "",
+        ].join("\n");
+        writeFile(join(dir, fileName), contents);
+    }
+}
+/**
+ * Copy plugin styles into `src/styles/plugins/<plugin-id>__<file>.css`
+ * and inject `@import` lines into `src/styles/global.css` between
+ * the marker comments. The marker block is replaced (not appended)
+ * so re-runs are idempotent.
+ */
+function emitPluginStyles(options) {
+    const stylesDir = join(options.outputDir, PLUGIN_STYLES_DIR_REL);
+    const imports = [];
+    if (options.styles.length > 0) {
+        mkdirSync(stylesDir, { recursive: true });
+        for (const { pluginId, paths } of options.styles) {
+            for (const p of paths) {
+                const ext = extname(p) || ".css";
+                const baseName = basename(p, ext);
+                const dest = `${slugifyPluginId(pluginId)}__${baseName}${ext}`;
+                copyFileSync(p, join(stylesDir, dest));
+                imports.push(`@import "./plugins/${dest}";`);
+            }
+        }
+    }
+    // Patch global.css. If the file doesn't exist (e.g. a partial
+    // scaffold), leave it alone — the scaffold emitter owns global.css.
+    const cssPath = join(options.outputDir, GLOBAL_CSS_REL);
+    if (!existsSync(cssPath))
+        return;
+    const current = readFileSync(cssPath, "utf-8");
+    const block = imports.length > 0
+        ? `${GLOBAL_CSS_BEGIN}\n${imports.join("\n")}\n${GLOBAL_CSS_END}`
+        : `${GLOBAL_CSS_BEGIN}\n${GLOBAL_CSS_END}`;
+    let next;
+    const beginIdx = current.indexOf(GLOBAL_CSS_BEGIN);
+    const endIdx = current.indexOf(GLOBAL_CSS_END);
+    if (beginIdx >= 0 && endIdx > beginIdx) {
+        next =
+            current.slice(0, beginIdx) +
+                block +
+                current.slice(endIdx + GLOBAL_CSS_END.length);
+    }
+    else {
+        // Append at end; ensure trailing newline.
+        const trimmed = current.endsWith("\n") ? current : `${current}\n`;
+        next = `${trimmed}${block}\n`;
+    }
+    writeFileSync(cssPath, next);
+}
+/**
+ * Write `astro.config.plugins.mjs` — a tiny module exporting:
+ *   - `pluginAliases`: Vite alias map for `virtual:dogsbay-plugin-config/<id>`
+ *   - `pluginFsAllow`: array of directory paths to add to
+ *     `vite.server.fs.allow`, so plugins shipped from absolute
+ *     paths outside the project root (workspace deps, monorepo
+ *     layouts) can be served by the Vite dev server.
+ *
+ * The user's `astro.config.mjs` imports both and spreads them
+ * into the appropriate Vite config slots.
+ */
+function emitPluginViteAliases(options) {
+    const aliasEntries = [];
+    for (const { pluginId } of options.clientConfigs) {
+        const target = `./${PLUGIN_CONFIG_DIR_REL}/${slugifyPluginId(pluginId)}.ts`;
+        aliasEntries.push(`  ${JSON.stringify(`virtual:dogsbay-plugin-config/${pluginId}`)}: new URL(${JSON.stringify(target)}, import.meta.url).pathname,`);
+    }
+    // Collect parent dirs of every clientModule + style file. Vite
+    // refuses to serve files outside the project root unless the
+    // path is on `server.fs.allow`. We add the immediate parent;
+    // Vite's allow check is recursive.
+    const fsAllowSet = new Set();
+    for (const { paths } of options.clientModules) {
+        for (const p of paths)
+            fsAllowSet.add(dirname(p));
+    }
+    for (const { paths } of options.styles) {
+        for (const p of paths)
+            fsAllowSet.add(dirname(p));
+    }
+    const contents = [
+        "// Auto-generated by dogsbay site build. Do not edit by hand.",
+        "// astro.config.mjs imports + spreads pluginAliases into",
+        "// vite.resolve.alias and pluginFsAllow into vite.server.fs.allow.",
+        "",
+        "export const pluginAliases = {",
+        ...aliasEntries,
+        "};",
+        "",
+        "export const pluginFsAllow = [",
+        ...Array.from(fsAllowSet).map((p) => `  ${JSON.stringify(p)},`),
+        "];",
+        "",
+    ].join("\n");
+    writeFile(join(options.outputDir, PLUGIN_VITE_REL), contents);
+}
+/**
+ * For each known slot, emit a `<Slot>Stack.astro` component that
+ * imports every contributing plugin's wrapper and recursively
+ * nests them. Plugin order maps to outer→inner — the first
+ * plugin's wrapper is the outermost.
+ *
+ * When no plugin contributes to a slot, the stack file is a
+ * passthrough (`<slot />`). Always emitting the file means
+ * per-page emission can unconditionally import and use the stack
+ * regardless of which plugins are loaded.
+ */
+function emitWrapperStacks(options) {
+    const wrappersDir = join(options.outputDir, PLUGIN_WRAPPERS_DIR_REL);
+    mkdirSync(wrappersDir, { recursive: true });
+    const groups = groupWrappersBySlot(options.componentWrappers ?? []);
+    for (const slot of KNOWN_SLOTS) {
+        const entries = groups.get(slot) ?? [];
+        const stackPath = join(wrappersDir, `${slot}Stack.astro`);
+        writeFile(stackPath, renderStack(slot, entries));
+    }
+}
+function groupWrappersBySlot(wrappers) {
+    const out = new Map();
+    for (const w of wrappers) {
+        const list = out.get(w.slot) ?? [];
+        list.push(w);
+        out.set(w.slot, list);
+    }
+    return out;
+}
+/**
+ * Render the source of `<Slot>Stack.astro`. Recursive nesting:
+ *   first plugin → outermost,
+ *   last plugin  → innermost,
+ *   final inner content → `<slot />`.
+ */
+function renderStack(slotName, entries) {
+    if (entries.length === 0) {
+        return [
+            `---`,
+            `// Auto-generated by dogsbay site build. No plugin contributed`,
+            `// a wrapper for the "${slotName}" slot — passthrough.`,
+            `---`,
+            ``,
+            `<slot />`,
+            ``,
+        ].join("\n");
+    }
+    // Build import statements, one per entry. Identifiers must be
+    // unique across the file — qualify with plugin id + index.
+    const importLines = [];
+    const componentNames = [];
+    entries.forEach((entry, idx) => {
+        const ident = `Wrap_${idx}_${slugifyIdent(entry.pluginId)}`;
+        importLines.push(`import ${ident} from ${JSON.stringify(entry.path)};`);
+        componentNames.push(ident);
+    });
+    // Pretty-print the nested body for readability — one tag per
+    // line with two-space indent per level.
+    const formatted = formatNested(componentNames);
+    return [
+        `---`,
+        `// Auto-generated by dogsbay site build. Wrappers contributed by:`,
+        ...entries.map((e, i) => `//   ${i + 1}. ${e.pluginId} → ${e.path}`),
+        `// Order: outer → inner = first → last plugin.`,
+        importLines.join("\n"),
+        `---`,
+        ``,
+        formatted,
+        ``,
+    ].join("\n");
+}
+/**
+ * Render an indented tree of nested wrapper components for
+ * readability. Output:
+ *   <A>
+ *     <B>
+ *       <slot />
+ *     </B>
+ *   </A>
+ */
+function formatNested(names) {
+    const lines = [];
+    names.forEach((name, idx) => {
+        const indent = "  ".repeat(idx);
+        lines.push(`${indent}<${name}>`);
+    });
+    lines.push(`${"  ".repeat(names.length)}<slot />`);
+    for (let i = names.length - 1; i >= 0; i--) {
+        const indent = "  ".repeat(i);
+        lines.push(`${indent}</${names[i]}>`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Convert a plugin id into a JavaScript-safe identifier suffix.
+ * Used as a uniqueness qualifier on the imported component name.
+ */
+function slugifyIdent(id) {
+    return id.replace(/[^A-Za-z0-9_]/g, "_");
+}
+/**
+ * Replace anything that's not safe in a filename / npm-package-
+ * subpath segment. Plugin ids look like `@dogsbay/plugin-image-zoom`
+ * or `@dogsbay/plugin-image-zoom#1`; slashes and `@` and `#` are
+ * the parts we need to flatten. The result is reversible enough
+ * for the user to figure out which file maps to which plugin.
+ */
+function slugifyPluginId(id) {
+    return id.replace(/^@/, "").replace(/\//g, "__").replace(/#/g, "_at_");
+}
+function writeFile(absPath, contents) {
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, contents);
+}
+/** Test-only: clear emitted plugin runtime files. */
+export function _clearPluginRuntime(outputDir) {
+    for (const rel of [PLUGIN_RUNTIME_REL, PLUGIN_VITE_REL]) {
+        rmSync(join(outputDir, rel), { force: true });
+    }
+    rmSync(join(outputDir, PLUGIN_CONFIG_DIR_REL), { recursive: true, force: true });
+    rmSync(join(outputDir, PLUGIN_STYLES_DIR_REL), { recursive: true, force: true });
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"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"}

package/dist/project.d.ts

@@ -0,0 +1,320 @@
+import type { ExportPage, NavItem } from "@dogsbay/types";
+export interface AstroProjectOptions {
+    siteName?: string;
+    theme?: string;
+    local?: boolean;
+    repoUrl?: string;
+    editUri?: string;
+    copyright?: string;
+    /**
+     * Brand keywords for the site. Emitted into `src/data/site.json`
+     * so the `seo/h1-brand-keyword` audit rule can read them.
+     */
+    brandKeywords?: string[];
+    /** Source project directory (for copying extra_css, assets, etc.) */
+    sourceDir?: string;
+    /** Custom CSS files from mkdocs.yml extra_css */
+    extraCss?: string[];
+    /** Enable Astro image optimization (copies to src/assets/ instead of public/) */
+    imageOptimization?: boolean;
+    /** Controls CodeBlock title bar: true = always (default), "auto" = only with explicit title, false = never */
+    codeBlockTitle?: boolean | "auto";
+    /** Section name — pages go under docs/{section}/, nav gets a top-level entry */
+    section?: string;
+    /**
+     * URL path prefix where pages are served. Default `"/docs"`. Set to
+     * `""` to serve at the host root, `"/handbook"` (etc.) for any
+     * other prefix. Threaded through every emitter that builds URLs,
+     * file output paths, or rewrites links — so changing this lifts
+     * the entire site to the new prefix in one shot. See
+     * `normalizeBasePath` and plans/configurable-base-path.md.
+     */
+    basePath?: string;
+    /**
+     * Path prefix for tag term pages, used when emitting the page-level
+     * `<TagList>` chip strip. Default `/tags` — match the indexPath
+     * declared in `dogsbay.config.yml`'s `taxonomies.tags` block.
+     */
+    tagsIndexPath?: string;
+    /**
+     * Per-prefix display config for tag chips (label + palette color).
+     * Sourced from `taxonomies.tags.prefixes`. Emitted into
+     * `site.json` and forwarded to `<TagList>` so chips render with
+     * prefix-keyed colors and two-part labels. Absent → flat chips.
+     * See plans/tag-display-config.md.
+     */
+    tagPrefixes?: import("@dogsbay/types").SiteConfig["tagPrefixes"];
+    /**
+     * Per-tag leaf-label overrides. Sourced from
+     * `taxonomies.tags.labels`. URLs continue to use slugs.
+     */
+    tagLabels?: import("@dogsbay/types").SiteConfig["tagLabels"];
+    /**
+     * Map of taxonomy name → index path, sourced from declared
+     * `taxonomies` entries. Lets renderer components surface a link
+     * from built-in field badges (`TypeBadge`, `StatusBadge`) when
+     * the user has opted in to a browse destination.
+     */
+    taxonomyIndexPaths?: import("@dogsbay/types").SiteConfig["taxonomyIndexPaths"];
+    /**
+     * Per-taxonomy display config (`prefixes` + `labels`), keyed by
+     * taxonomy name. Powers the search-facet UI; mirrors the same
+     * data the chip components consume but in a per-taxonomy shape.
+     * See plans/search-facets.md.
+     */
+    taxonomyDisplay?: import("@dogsbay/types").SiteConfig["taxonomyDisplay"];
+    /** Canonical site URL — required for sitemap.xml + canonical tags */
+    siteUrl?: string;
+    /** Site-wide description used as default <meta name="description"> */
+    description?: string;
+    /** Default OG image URL (1200×630 PNG/JPG) */
+    ogImage?: string;
+    /** Twitter / X handle including "@" */
+    twitterHandle?: string;
+    /** Theme color hint for browsers (hex) */
+    themeColor?: string;
+    /** Plausible domain — when set, docs-layout emits the tracker script */
+    plausibleDomain?: string;
+    /** Optional Plausible script URL override (for self-hosted) */
+    plausibleScriptUrl?: string;
+    /**
+     * Declared versions for the version axis. When present and ≥2,
+     * `emitSwitcherMap` emits `src/data/switcherMap.json` with per-
+     * page version equivalents and a header with this list (so the
+     * VersionSwitcher component can render labels + EOL marks even
+     * when a page is missing an equivalent in some version).
+     *
+     * See plans/multi-source-content.md and
+     * docs-dev/multi-source-architecture.md.
+     */
+    versions?: Array<{
+        id: string;
+        label?: string;
+        eol?: boolean;
+    }>;
+    /**
+     * Which version is the default. Marked in switcherMap.json so
+     * the switcher can highlight it; PR 4c wires the default-
+     * version redirect that uses this same field.
+     */
+    defaultVersion?: string;
+    /**
+     * Declared locales for the i18n axis. Same role as
+     * `versions` for the locale axis.
+     */
+    locales?: Array<{
+        id: string;
+        label?: string;
+    }>;
+    /**
+     * Which locale is the default. Used for the default-locale
+     * redirect AND the missing-translation fallback.
+     */
+    defaultLocale?: string;
+    /**
+     * When set, emit a deploy config file + dev dep + script for the
+     * named platform. Only "cloudflare-workers" supported today.
+     * Other adapters (netlify, vercel, gh-pages) follow the same shape;
+     * left unimplemented per Phase 1 scope.
+     */
+    deploy?: "cloudflare-workers";
+    /**
+     * Overwrite all files including maintainer-customizable scaffold
+     * files (theme.css, astro.config.mjs, package.json, site.json,
+     * tsconfig.json, wrangler.jsonc, ui component copies). Default
+     * behaviour: scaffold those files only on first run; on subsequent
+     * runs leave them alone and regenerate ONLY the auto-managed files
+     * (`src/pages/docs/**`, `src/data/nav.json`, `public/robots.txt`).
+     *
+     * Use this when intentionally re-scaffolding (theme upgrade, deploy
+     * target switch, etc.) and you've reviewed the diff.
+     */
+    force?: boolean;
+    /**
+     * Emit `public/llms.txt`, `public/llms-full.txt`, and per-section
+     * `public/<dir>/llms.txt` files for LLM discovery. Default `true`.
+     * Disable when the host enforces a different content policy or when
+     * the site is private / not for agent consumption.
+     */
+    llmsTxt?: boolean;
+    /**
+     * Emit a companion `<page>.md.ts` Astro endpoint for every generated
+     * page so agents can fetch raw Dogsbay-MD at `<page>.md`. Prerendered
+     * to static `.md` files in `dist/`. Default `true`.
+     */
+    mdMirror?: boolean;
+    /**
+     * `Content-Signal` directive for the AI training corpus permission
+     * emitted in robots.txt. Default `"no"` — opt out of training by
+     * default; writers explicitly opt in by passing `"yes"`.
+     */
+    aiTrain?: "yes" | "no";
+    /**
+     * `Content-Signal` directive for AI inference / agent read-time
+     * access emitted in robots.txt. Default `"yes"` — agents reading
+     * docs at user-request time is the whole point of agent-readiness.
+     */
+    aiInput?: "yes" | "no";
+    /**
+     * `Content-Signal` directive for inclusion in agent and human
+     * search results emitted in robots.txt. Default `"yes"`.
+     */
+    aiSearch?: "yes" | "no";
+    /**
+     * Per-page LLM action UI ("Copy as markdown", "Open in Claude/
+     * ChatGPT/Perplexity/Gemini"). When omitted, the cluster is not
+     * rendered. Independent of `mdMirror` / `llmsTxt` — those drive
+     * the data layer, this drives the human UI on top.
+     * See plans/llm-page-actions.md.
+     */
+    llmActions?: import("@dogsbay/types").SiteConfig["llmActions"];
+}
+/**
+ * Export pages + nav to a complete Astro project directory.
+ *
+ * Thin orchestrator. The heavy lifting lives in four focused emitters
+ * (one per emission tier) that this function calls in sequence:
+ *
+ *   1. emitSiteScaffold       — Tier 2 (scaffold-once): package.json,
+ *                               theme, astro.config.mjs, components, etc.
+ *   2. emitAstroPages          — Tier 1 (content): nav.json, .astro pages,
+ *                               .md mirror endpoints (when enabled)
+ *   3. emitConfigDerivedFiles  — Tier 1 (config-derived): robots.txt
+ *   4. emitAgentReadinessFiles — Tier 1 (agent-tier): llms.txt, _headers,
+ *                               middleware.ts (when enabled)
+ *
+ * Each emitter is also callable directly — site init / site build (in
+ * progress) call only the subset they need.
+ */
+export declare function exportAstroProject(pages: ExportPage[], nav: NavItem[], outputDir: string, options?: AstroProjectOptions): Promise<void>;
+/**
+ * Emit the project scaffold: package.json, astro.config.mjs, tsconfig,
+ * theme/global CSS, site.json, copied UI components, deploy config.
+ *
+ * @returns the count of files skipped because the project is already
+ *   scaffolded (used by the orchestrator's "preserved N files" log).
+ */
+/**
+ * Emit `src/data/site.json` from the resolved options. Pure
+ * config-derived (Tier 1) — overwrites unconditionally so config
+ * edits in `dogsbay.config.yml` propagate to the rendered site on
+ * every `dogsbay site build` without needing `--force`.
+ *
+ * Standalone helper so `site build` can refresh it without going
+ * through the full scaffold path. `emitSiteScaffold` also calls it.
+ */
+export declare function emitSiteConfig(outputDir: string, siteName: string, options: AstroProjectOptions): void;
+export declare function emitSiteScaffold(outputDir: string, siteName: string, options: AstroProjectOptions, writeScaffold: boolean): number;
+/**
+ * Emit content-tier files: nav.json, every page's .astro, the per-page
+ * .md mirror endpoint (when `mdMirror` is enabled), and the index
+ * redirect. Returns the count of pages emitted and the merged nav for
+ * downstream consumers (llms.txt builder).
+ */
+export declare function emitAstroPages(pages: ExportPage[], nav: NavItem[], outputDir: string, options: AstroProjectOptions): Promise<{
+    generated: number;
+    outputNav: NavItem[];
+}>;
+/**
+ * Emit `public/robots.txt` with `Content-Signal` directives + sitemap
+ * link. Always overwrites — the file's contents are pure derivation
+ * from `options`. Maintainers wanting custom Disallow rules layer
+ * them at the CDN level.
+ */
+export declare function emitConfigDerivedFiles(outputDir: string, options: AstroProjectOptions): void;
+/**
+ * Shape of the emitted `src/data/switcherMap.json` file.
+ * Switcher components import this JSON directly, so the shape
+ * is also the runtime contract.
+ *
+ * Each `byLogicalKey` value is a FLAT LIST of variants — every
+ * (locale, version) combo where this logical page exists, with
+ * its full URL. Switcher components filter the list to find
+ * relevant alternates:
+ *
+ *   - VersionSwitcher filters where `locale === currentLocale`
+ *     (so the dropdown only crosses the version axis).
+ *   - LocaleSwitcher filters where `version === currentVersion`.
+ *
+ * For axes that aren't active site-wide, the field is undefined
+ * on every variant; switchers for that axis simply render
+ * nothing.
+ */
+export interface SwitcherMap {
+    /**
+     * Declared versions in declaration order. The component uses
+     * this to render the dropdown in canonical order even when
+     * some entries are missing from a given page's variants list
+     * (those entries render as greyed-out / "no equivalent").
+     */
+    versions: Array<{
+        id: string;
+        label?: string;
+        eol?: boolean;
+        default?: boolean;
+    }>;
+    /**
+     * Declared locales in declaration order. Same role as
+     * `versions` but for the i18n axis.
+     */
+    locales: Array<{
+        id: string;
+        label?: string;
+        default?: boolean;
+    }>;
+    /**
+     * Per-logical-key list of variants. Logical key is
+     * `<namespace>/<originalSlug>` (namespace defaults to "docs"
+     * when the namespace axis is inactive). Each variant carries
+     * the full URL plus the (locale, version) combo it represents.
+     */
+    byLogicalKey: Record<string, SwitcherVariant[]>;
+}
+export interface SwitcherVariant {
+    /** Present when the locale axis is active for this site. */
+    locale?: string;
+    /** Present when the version axis is active for this site. */
+    version?: string;
+    /** Full URL (with basePath) for this variant. */
+    url: string;
+}
+/**
+ * Emit `src/data/switcherMap.json` describing per-page
+ * version + locale equivalents. Always writes the file —
+ * even when no axis is active — with empty `versions: []`,
+ * `locales: []`, `byLogicalKey: {}`. Keeps the per-page
+ * static import working in every site, with switchers
+ * rendering nothing when their axis has < 2 declared entries.
+ *
+ * Pages without `multiSource` metadata are skipped — they
+ * aren't part of any axis, so they don't appear in any
+ * switcher. Pages with multiSource (any axis active) DO
+ * appear, even when this particular page sits in the
+ * default-bucket of the relevant axis (e.g. an unversioned
+ * baseline page in a multi-version site).
+ */
+export declare function emitSwitcherMap(pages: ExportPage[], outputDir: string, options: AstroProjectOptions): void;
+/**
+ * Emit redirect stub pages for missing translations. For each
+ * page that exists in the default locale, ensure there's a
+ * corresponding URL for every other declared locale: if no
+ * page already exists at that URL, write a stub Astro page
+ * that 302-redirects to the default-locale equivalent.
+ *
+ * Stubs aren't emitted FROM other-locale TO default-locale —
+ * only the other way. The default locale is the canonical
+ * baseline; if a writer authored content only in (say) `fr`,
+ * we don't manufacture an `en` URL with a fake redirect.
+ */
+export declare function emitMissingTranslationStubs(pages: ExportPage[], outputDir: string, options: AstroProjectOptions): void;
+/**
+ * Emit agent-readiness files: `public/llms.txt` + `llms-full.txt` +
+ * per-section indexes when `llmsTxt` is enabled; `public/_headers`
+ * (Cloudflare Link header) alongside; and `src/middleware.ts` when
+ * `mdMirror` is enabled.
+ *
+ * `.md` mirror endpoints themselves are emitted per-page inside
+ * `emitAstroPages` (they share the page-loop's serialization step).
+ */
+export declare function emitAgentReadinessFiles(pages: ExportPage[], outputNav: NavItem[], outputDir: string, siteName: string, options: AstroProjectOptions): void;
+//# sourceMappingURL=project.d.ts.map