@ascribed/astro 0.2.1-next.9 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,10 @@
 import type { AstroIntegration } from "astro";
+import { type ProjectEntry } from "./projects.js";
 export { default as rehypeAscribeAttributes } from "./rehype.js";
 export { satteriAscribeAttributes } from "./satteri.js";
-/** Options of the integration. */
-export interface AscribeOptions {
-    /** The build whose site output is the collection (a name in `ascribe.toml`). */
-    build: string;
-    /** The directory holding `ascribe.toml`, relative to the Astro root. Default: the root. */
-    project?: string;
+export type { ProjectEntry } from "./projects.js";
+/** Options every form of the integration takes. */
+interface SharedOptions {
     /**
      * The `ascribe` binary, relative to the Astro root. Default: `ASCRIBE_BIN`, then
      * the platform binary installed with `@ascribed/cli`.
@@ -22,15 +20,48 @@ export interface AscribeOptions {
      * Review in the site preview: an **Ascribe review** app in `astro dev`'s
      * toolbar, which marks the page's changes and shows the pull request's
      * comments, with source anchors in `astro dev`. Default `true`; `false`
-     * removes the app. `astro build` never has it.
+     * removes the app. `astro build` never has it. With several projects, it
+     * reviews one: the entry a name names, or the first for `true`.
      */
-    review?: boolean;
+    review?: boolean | string;
     /**
      * Show a code block's title (`title="…"` in its info string, as `@snippet`
      * writes it) above it, with a Shiki transformer that puts the block in a
      * `<figure class="code-title">` with a `<figcaption>`. Default `true`.
      */
     codeTitles?: boolean;
+    /**
+     * The site's one sitemap, at `<base>sitemap.xml`, of every listed page of
+     * every project and every page of the site's own. `exclude` lists routes,
+     * from the host's root, of the site's own pages to leave out of it, such
+     * as one that carries `noindex`.
+     */
+    sitemap?: {
+        exclude?: string[];
+    };
 }
-/** Runs `ascribe build`, checks the site's routing, adds the markdown plugin, and serves published files. */
+/** Options of the integration with one project. */
+export interface OneProjectOptions extends SharedOptions {
+    /** The build whose site output is the collection (a name in `ascribe.toml`). */
+    build: string;
+    /** The directory holding `ascribe.toml`, relative to the Astro root. Default: the root. */
+    project?: string;
+    projects?: never;
+}
+/** Options of the integration with several projects, each entry named. */
+export interface ProjectsOptions extends SharedOptions {
+    /** The projects, each a named build of a project; two entries may share a project. */
+    projects: ProjectEntry[];
+    build?: never;
+    project?: never;
+}
+/** Options of the integration. */
+export type AscribeOptions = OneProjectOptions | ProjectsOptions;
+/**
+ * Runs `ascribe build` for each project, checks the site's routing, adds the markdown plugin, adds a
+ * page for each permalink's address, and serves published files, and, with `[consumer] agents = true`,
+ * `llms.txt` and each page's Markdown, each at its project's base path; and writes the site's one
+ * sitemap and `robots.txt` from every project's page records, and, with `[consumer] headers =
+ * "netlify"`, its `_headers` from their headers lists.
+ */
 export default function ascribe(options: AscribeOptions): AstroIntegration;

package/dist/index.js

@@ -4,7 +4,8 @@
 //   // astro.config.mjs
 //   import ascribe from "@ascribed/astro";
 //   export default defineConfig({
-//     base: "/docs", trailingSlash: "never",     // as in ascribe.toml's [consumer]
+//     // `site`, `base`, and `trailingSlash` come from ascribe.toml's
+//     // [consumer] when they're left out here; set here, they must agree.
 //     integrations: [ascribe({ build: "site" })],
 //   });
 //
@@ -19,56 +20,161 @@
 //   // a layout
 //   import Elements from "@ascribed/astro/Elements.astro";           // <Elements /> in <head>
 //   import Availability from "@ascribed/astro/Availability.astro";   // the page's availability
+//   import Head from "@ascribed/astro/Head.astro";                   // <Head entry={entry} /> in <head>
+//
+//   // the sidebar: src/nav.ts's list, checked against the collection
+//   import { sidebar } from "@ascribed/astro/content";
+//   const groups = sidebar(nav, await getCollection("docs"));
+//
+//   // src/pages/404.astro
+//   import MissingPermalink from "@ascribed/astro/MissingPermalink.astro"; // a permalink that isn't here
+//
+// Several projects in one site, each entry named, and each collection naming its entry:
+//
+//   ascribe({
+//     projects: [
+//       { name: "docs", project: "../docs", build: "site" },
+//       { name: "home", project: "home", build: "site" },
+//     ],
+//     review: "docs",
+//   })
+//   ascribeCollection({ schema, name: "docs" })
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findBinary } from "./binary.js";
 import { codeTitles } from "./code-titles.js";
 import { SeenFiles, watchDev } from "./dev.js";
-import { copyPublishedFiles, filesMiddleware } from "./files.js";
-import { consumerMismatches, readProject } from "./project.js";
+import { agentsMiddleware, copyAgentFiles, copyPublishedFiles, filesMiddleware, folderUnder, } from "./files.js";
+import { WARN as HEAD_WARN } from "./head-check.js";
+import { headersFor, headersOutcome, mergeRules, readHeaders } from "./headers.js";
+import { forwardingRoutes, hasPermalinks, permalinkPattern, readPermalinks } from "./permalinks.js";
+import { consumerMismatches, homeRoute, normalizeBase, readProject, supplyRouting, } from "./project.js";
+import { basePathClashes, nameProblems, pagesUnderOtherPaths, permalinkProblems, } from "./projects.js";
+import { pageList, readRecords, routeAs, routeKey, sitemapRoute, } from "./records.js";
 import rehypeAscribeAttributes from "./rehype.js";
 import { removeDevFile, siteUrl, writeDevFile } from "./review/devfile.js";
-import { runDiff } from "./review/diff.js";
+import { runDiff, runPrompt } from "./review/diff.js";
 import { APP_ID } from "./review/protocol.js";
 import { readRoutes } from "./review/routes.js";
 import { channelProblem, ReviewServer } from "./review/server.js";
+import { devRouted, devSitePages, rootFiles, rootFilesMiddleware, } from "./root-files.js";
 import { anchorsFor, hasWarnings, reviewFor, runBuild } from "./run.js";
 import { satteriAscribeAttributes } from "./satteri.js";
 import { copySchema } from "./schema.js";
 export { default as rehypeAscribeAttributes } from "./rehype.js";
 export { satteriAscribeAttributes } from "./satteri.js";
-/** The virtual module `content.ts` reads the resolved site output root from. */
+/** The virtual module `content.ts` reads the resolved site output roots from. */
 const SITE_MODULE = "virtual:ascribe/site";
 /** The toolbar app's icon: a speech bubble over a page. */
 const ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3h8l4 4v6"/><path d="M14 3v4h4"/><path d="M6 3v15"/><path d="M11 14h10v6h-6l-3 2v-2h-1z"/></svg>';
-/** Runs `ascribe build`, checks the site's routing, adds the markdown plugin, and serves published files. */
+function fail(problems, what) {
+    if (problems.length > 0)
+        throw new Error(`@ascribed/astro: ${what}:\n- ${problems.join("\n- ")}`);
+}
+/**
+ * Runs `ascribe build` for each project, checks the site's routing, adds the markdown plugin, adds a
+ * page for each permalink's address, and serves published files, and, with `[consumer] agents = true`,
+ * `llms.txt` and each page's Markdown, each at its project's base path; and writes the site's one
+ * sitemap and `robots.txt` from every project's page records, and, with `[consumer] headers =
+ * "netlify"`, its `_headers` from their headers lists.
+ */
 export default function ascribe(options) {
-    let siteRoot = "";
-    let devProject;
-    let devConfig;
-    let rebuild;
+    /** With `projects`; otherwise the one entry has no name a collection gives. */
+    const named = options.projects !== undefined;
+    let entries = [];
+    let groups = [];
+    let routing;
     /** The dev server's sources as its first build read them. */
     const seen = new SeenFiles();
     let binary;
-    let reviewing = false;
+    let reviewed;
+    let devCommand = false;
     let devHttps = false;
     let review;
+    /** The site's routes, as Astro resolved them, for what `astro dev` serves of the site's own. */
+    let astroRoutes = [];
+    /** The site's `public/` folder, where its own `robots.txt` would be. */
+    let publicDir = "";
+    /** What the sitemap and `robots.txt` are drawn from, given the site's pages and its routes. */
+    const rootSources = (sitePages, routed) => {
+        const base = routing?.base ?? "/";
+        const records = entries.map((entry) => readRecords(entry.siteRoot));
+        // Entries of one project share its `ascribe.toml`, and so what it says to crawlers.
+        const robots = new Map();
+        for (const [i, entry] of entries.entries()) {
+            if (!robots.has(entry.project.dir))
+                robots.set(entry.project.dir, {
+                    name: entry.name,
+                    robots: records[i]?.robots ?? { lines: [] },
+                });
+        }
+        const root = normalizeBase(base);
+        return {
+            projects: records.map(pageList),
+            routed,
+            sitePages,
+            excluded: [
+                ...forwardingRoutes(entries.map((entry) => readPermalinks(entry.siteRoot))),
+                `${root}404`,
+                `${root}500`,
+                ...(options.sitemap?.exclude ?? []),
+            ],
+            robots: [...robots.values()],
+            site: routing?.site,
+            base,
+            ownRobots: existsSync(path.join(publicDir, "robots.txt")),
+            ownSitemap: existsSync(path.join(publicDir, "sitemap.xml")),
+        };
+    };
     return {
         name: "@ascribed/astro",
         hooks: {
-            "astro:config:setup": async ({ config, command, logger, updateConfig, addDevToolbarApp, createCodegenDir, }) => {
+            "astro:config:setup": async ({ config, command, logger, updateConfig, addDevToolbarApp, createCodegenDir, injectRoute, addMiddleware, }) => {
                 const root = fileURLToPath(config.root);
-                const project = readProject(path.resolve(root, options.project ?? "."));
-                // An unknown build is `ascribe build`'s to report: it knows the implicit `site` build.
-                siteRoot = project.siteRoot(options.build);
-                // `ascribe.toml`'s routing must be Astro's, or every link Ascribe writes is wrong.
-                const problems = consumerMismatches(project, {
-                    base: config.base,
-                    trailingSlash: config.trailingSlash,
-                    site: config.site,
+                publicDir = fileURLToPath(config.publicDir);
+                const list = options.projects ?? [
+                    {
+                        name: "",
+                        build: options.build,
+                        ...(options.project === undefined ? {} : { project: options.project }),
+                    },
+                ];
+                if (named)
+                    fail(nameProblems(list), "the `projects` option is wrong");
+                const codegen = command === "preview" ? "" : fileURLToPath(createCodegenDir());
+                entries = list.map((entry) => {
+                    const project = readProject(path.resolve(root, entry.project ?? "."));
+                    return {
+                        name: entry.name,
+                        build: entry.build,
+                        project,
+                        // An unknown build is `ascribe build`'s to report: it knows the implicit `site` build.
+                        siteRoot: project.siteRoot(entry.build),
+                        agentsRoot: project.consumer.agents ? project.plainRoot(entry.build) : undefined,
+                        schemaDir: named ? path.join(codegen, entry.name) : codegen,
+                    };
                 });
-                if (problems.length > 0) {
-                    throw new Error(`@ascribed/astro: ascribe.toml and astro.config disagree:\n- ${problems.join("\n- ")}`);
+                // What astro.config leaves unset comes from [consumer]: `site` and `trailingSlash` from the
+                // first project that has them, and with one project, `base` from its base path. With
+                // `projects`, `base` stays the site's, the root every base path is under.
+                const { routing: astro, supplied } = supplyRouting(entries.map((entry) => entry.project), { base: config.base, trailingSlash: config.trailingSlash, site: config.site }, !named);
+                // `ascribe.toml`'s routing must be Astro's, or every link Ascribe writes is wrong.
+                for (const entry of entries) {
+                    fail(consumerMismatches(entry.project, astro), named
+                        ? `"${entry.name}"'s ascribe.toml and astro.config disagree`
+                        : "ascribe.toml and astro.config disagree");
+                }
+                fail(basePathClashes(entries), "two projects share a base path");
+                if (typeof options.review === "string" && !entries.some((e) => e.name === options.review)) {
+                    throw new Error(`@ascribed/astro: \`review\` names "${options.review}", and no entry of \`projects\` has that name.`);
+                }
+                if (reviewFor(options.review, command)) {
+                    reviewed =
+                        typeof options.review === "string"
+                            ? entries.find((e) => e.name === options.review)
+                            : entries[0];
                 }
                 // Where a markdown plugin goes depends on the processor Astro 7.3 runs.
                 const processor = config.markdown.processor;
@@ -83,13 +189,8 @@ export default function ascribe(options) {
                     throw new Error(`@ascribed/astro: the markdown processor "${processor.name}" is not one it can add its plugin to. ` +
                         "Use Astro's default (satteri) or unified(), or add `rehypeAscribeAttributes` to your own.");
                 }
-                devConfig = {
-                    base: config.base,
-                    trailingSlash: config.trailingSlash,
-                    site: config.site,
-                };
-                reviewing = reviewFor(options.review, command);
-                if (reviewing) {
+                routing = astro;
+                if (reviewed !== undefined) {
                     addDevToolbarApp({
                         id: APP_ID,
                         name: "Ascribe review",
@@ -100,18 +201,21 @@ export default function ascribe(options) {
                 if (command !== "preview") {
                     const found = findBinary({ binary: options.binary, root });
                     binary = found;
-                    // The schema's copy inside the Astro root, for content.config.ts to import.
-                    const codegen = fileURLToPath(createCodegenDir());
-                    rebuild = async () => {
-                        logger.info(`running ${path.basename(found)} build for "${options.build}"`);
+                    const buildEntry = async (entry) => {
+                        logger.info(`running ${path.basename(found)} build for "${entry.build}"${named ? ` (${entry.name})` : ""}`);
                         const result = await runBuild({
                             binary: found,
-                            configPath: project.configPath,
-                            build: options.build,
-                            cwd: project.dir,
-                            anchors: anchorsFor(options.anchors, command, reviewing),
-                            // While review is on, the JSON output says which page is at each route.
-                            outputs: review?.active ? ["site", "json"] : ["site"],
+                            configPath: entry.project.configPath,
+                            build: entry.build,
+                            cwd: entry.project.dir,
+                            anchors: anchorsFor(options.anchors, command, entry === reviewed),
+                            outputs: [
+                                "site",
+                                // `llms.txt` and each page's Markdown, which agents read.
+                                ...(entry.agentsRoot === undefined ? [] : ["plain"]),
+                                // While review is on, the JSON output says which page is at each route.
+                                ...(entry === reviewed && review?.active ? ["json"] : []),
+                            ],
                         });
                         if (hasWarnings(result.diagnostics))
                             logger.warn(result.diagnostics);
@@ -119,17 +223,69 @@ export default function ascribe(options) {
                             logger.info(result.diagnostics);
                         if (result.summary !== "")
                             logger.info(result.summary);
-                        copySchema(siteRoot, codegen);
+                        // The schema's copy inside the Astro root, for content.config.ts to import.
+                        mkdirSync(entry.schemaDir, { recursive: true });
+                        copySchema(entry.siteRoot, entry.schemaDir);
+                    };
+                    // What the projects share, which no one project's build can see.
+                    const checkShared = () => {
+                        if (entries.length < 2)
+                            return;
+                        const current = entries.map((entry) => ({
+                            ...entry,
+                            project: readProject(entry.project.dir),
+                        }));
+                        fail(basePathClashes(current), "two projects share a base path");
+                        fail(pagesUnderOtherPaths(current), "a page is under another project's base path");
+                        fail(permalinkProblems(current, current.map((entry) => readPermalinks(entry.siteRoot))), "the projects' permalinks can't share one route");
                     };
+                    // One group for each project: a change rebuilds the project it's in.
+                    const byDir = new Map();
+                    for (const entry of entries) {
+                        byDir.set(entry.project.dir, [...(byDir.get(entry.project.dir) ?? []), entry]);
+                    }
+                    groups = [...byDir.values()].map((group) => ({
+                        project: group[0].project,
+                        entries: group,
+                        rebuild: async () => {
+                            for (const entry of group)
+                                await buildEntry(entry);
+                            checkShared();
+                        },
+                    }));
                     // The sources as the first build reads them: the watcher may report their edits late.
-                    if (command === "dev")
-                        seen.prime([project.contentRoot, project.configPath]);
-                    await rebuild();
-                    if (command === "dev")
-                        devProject = project;
+                    if (command === "dev") {
+                        for (const group of groups)
+                            seen.prime([group.project.contentRoot, group.project.configPath]);
+                    }
+                    for (const entry of entries)
+                        await buildEntry(entry);
+                    checkShared();
+                    devCommand = command === "dev";
+                    if (devCommand) {
+                        // A tag of the head written twice, by Head.astro and the layout, is warned about.
+                        globalThis[HEAD_WARN] = (message) => logger.warn(message);
+                        addMiddleware({
+                            entrypoint: new URL("./head-check.js", import.meta.url),
+                            order: "post",
+                        });
+                    }
+                    // Each permalink's address, a page that forwards to its heading. One route serves every
+                    // list, at the path of the first that names anything.
+                    const lists = entries.flatMap((entry) => readPermalinks(entry.siteRoot) ?? []);
+                    const served = lists.find(hasPermalinks) ?? lists[0];
+                    if (served !== undefined) {
+                        injectRoute({
+                            pattern: permalinkPattern(served.path, astro.base),
+                            entrypoint: new URL("../src/Permalink.astro", import.meta.url),
+                            prerender: true,
+                        });
+                    }
                 }
-                // Dev serving of `_ascribe/files/`; the build copies them in `astro:build:done`.
+                const projectHome = (entry) => homeRoute(entry.project.consumer.basePath, astro.trailingSlash);
+                // Dev serving of `_ascribe/files/`, and of the plain output for agents; the build copies them in `astro:build:done`.
                 updateConfig({
+                    ...supplied,
                     ...(options.codeTitles === false
                         ? {}
                         : { markdown: { shikiConfig: { transformers: [codeTitles] } } }),
@@ -141,83 +297,162 @@ export default function ascribe(options) {
                                 name: "@ascribed/astro:site",
                                 resolveId: (id) => (id === SITE_MODULE ? `\0${SITE_MODULE}` : undefined),
                                 load: (id) => id === `\0${SITE_MODULE}`
-                                    ? `export const siteRoot = ${JSON.stringify(siteRoot)};`
+                                    ? `export const siteRoot = ${JSON.stringify(entries[0]?.siteRoot ?? "")};\n` +
+                                        `export const astroRoot = ${JSON.stringify(root)};\n` +
+                                        `export const home = ${JSON.stringify(homeRoute(astro.base, astro.trailingSlash))};\n` +
+                                        `export const collections = ${JSON.stringify(named ? Object.fromEntries(entries.map((e) => [e.name, e.siteRoot])) : {})};\n` +
+                                        `export const permalinks = ${JSON.stringify(entries.map((e) => ({ siteRoot: e.siteRoot, home: projectHome(e) })))};\n` +
+                                        `export const routes = ${JSON.stringify(entries.map((e) => ({
+                                            siteRoot: e.siteRoot,
+                                            basePath: e.project.consumer.basePath,
+                                            trailingSlash: e.project.consumer.trailingSlash,
+                                        })))};`
                                     : undefined,
                             },
                             {
                                 name: "@ascribed/astro:files",
                                 configureServer(server) {
-                                    server.middlewares.use(filesMiddleware(siteRoot, config.base.endsWith("/") ? config.base : `${config.base}/`));
+                                    for (const entry of entries) {
+                                        const base = entry.project.consumer.basePath;
+                                        server.middlewares.use(filesMiddleware(entry.siteRoot, base));
+                                        if (entry.agentsRoot !== undefined) {
+                                            const siteRoot = entry.siteRoot;
+                                            server.middlewares.use(agentsMiddleware(entry.agentsRoot, base, (pathname) => headersFor(siteRoot, pathname)));
+                                        }
+                                    }
+                                    // The sitemap and robots.txt, as the build would write them now.
+                                    server.middlewares.use(rootFilesMiddleware(astro.base, () => rootFiles(rootSources(devSitePages(astroRoutes, astro), devRouted(astroRoutes, astro)))));
                                 },
                             },
                         ],
                     },
                 });
             },
+            "astro:routes:resolved": ({ routes }) => {
+                astroRoutes = routes;
+            },
             "astro:server:setup": ({ server, refreshContent, logger, toolbar }) => {
-                if (devProject && rebuild && devConfig) {
-                    if (!refreshContent)
-                        throw new Error("@ascribed/astro: this Astro version does not support refreshContent.");
-                    const project = devProject;
-                    devHttps = Boolean(server.config.server.https);
-                    const builds = watchDev({
+                if (!devCommand || !routing)
+                    return;
+                if (!refreshContent)
+                    throw new Error("@ascribed/astro: this Astro version does not support refreshContent.");
+                devHttps = Boolean(server.config.server.https);
+                for (const group of groups) {
+                    group.builds = watchDev({
                         server,
                         seen,
                         refreshContent: () => refreshContent({}),
                         logger,
-                        project,
-                        astro: devConfig,
-                        build: options.build,
-                        rebuild,
-                        onBuilt: () => review?.rebuilt(),
+                        project: group.project,
+                        astro: routing,
+                        builds: group.entries.map((entry) => entry.build),
+                        rebuild: group.rebuild,
+                        onBuilt: () => {
+                            if (reviewed !== undefined && group.entries.includes(reviewed))
+                                review?.rebuilt();
+                        },
+                    });
+                }
+                const group = groups.find((g) => reviewed !== undefined && g.entries.includes(reviewed));
+                if (reviewed !== undefined && group?.builds !== undefined && binary !== undefined) {
+                    const entry = reviewed;
+                    const builds = group.builds;
+                    const run = { binary, configPath: entry.project.configPath, cwd: entry.project.dir };
+                    const jsonRoot = path.join(path.dirname(entry.siteRoot), "json");
+                    review = new ReviewServer({
+                        channel: toolbar,
+                        logger,
+                        build: entry.build,
+                        contentRoot: entry.project.contentRoot,
+                        channelProblem: channelProblem(server.config),
+                        diff: (base) => runDiff({ ...run, build: entry.build, base }),
+                        prompt: (page, base) => runPrompt({ ...run, build: entry.build, base, path: page }),
+                        projectDir: entry.project.dir,
+                        connect: async () => (await import("./review/github.js")).connect(entry.project.dir),
+                        writeRoutes: () => builds.inTurn(async () => {
+                            await runBuild({ ...run, build: entry.build, outputs: ["json"] });
+                        }),
+                        readRoutes: () => readRoutes(jsonRoot),
                     });
-                    if (reviewing && binary !== undefined) {
-                        const found = binary;
-                        const run = { binary: found, configPath: project.configPath, cwd: project.dir };
-                        const jsonRoot = path.join(path.dirname(siteRoot), "json");
-                        review = new ReviewServer({
-                            channel: toolbar,
-                            logger,
-                            build: options.build,
-                            contentRoot: project.contentRoot,
-                            channelProblem: channelProblem(server.config),
-                            diff: (base) => runDiff({ ...run, build: options.build, base }),
-                            connect: async () => (await import("./review/github.js")).connect(project.dir),
-                            writeRoutes: () => builds.inTurn(async () => {
-                                await runBuild({ ...run, build: options.build, outputs: ["json"] });
-                            }),
-                            readRoutes: () => readRoutes(jsonRoot),
-                        });
-                    }
                 }
             },
             "astro:server:start": ({ address, logger }) => {
                 review?.listening(address.address);
-                if (!devProject || !devConfig)
+                if (!devCommand)
                     return;
-                const dir = devProject.dir;
-                try {
-                    writeDevFile(dir, {
-                        url: siteUrl(address, { https: devHttps, base: devConfig.base }),
-                        build: options.build,
-                        pid: process.pid,
-                    });
-                    // Vite exits on a signal before `astro:server:done` runs.
-                    process.once("exit", () => removeDevFile(dir, process.pid));
-                }
-                catch (error) {
-                    logger.warn(`couldn't write .ascribe/dev.json, which the editor's Open Site Preview reads: ${error instanceof Error ? error.message : String(error)}`);
+                // Each project's folder gets its own file, with its own address: its base path.
+                for (const group of groups) {
+                    const entry = group.entries[0];
+                    const dir = group.project.dir;
+                    try {
+                        writeDevFile(dir, {
+                            url: siteUrl(address, { https: devHttps, base: entry.project.consumer.basePath }),
+                            build: entry.build,
+                            pid: process.pid,
+                        });
+                        // Vite exits on a signal before `astro:server:done` runs.
+                        process.once("exit", () => removeDevFile(dir, process.pid));
+                    }
+                    catch (error) {
+                        logger.warn(`couldn't write ${groups.length > 1 ? path.join(dir, ".ascribe", "dev.json") : ".ascribe/dev.json"}, which the editor's Open Site Preview reads: ${error instanceof Error ? error.message : String(error)}`);
+                    }
                 }
             },
             "astro:server:done": () => {
                 review?.dispose();
                 review = undefined;
-                if (devProject)
-                    removeDevFile(devProject.dir, process.pid);
+                if (devCommand)
+                    for (const group of groups)
+                        removeDevFile(group.project.dir, process.pid);
             },
-            "astro:build:done": async ({ dir, logger }) => {
-                if (await copyPublishedFiles(siteRoot, dir))
-                    logger.info("copied _ascribe/files/");
+            "astro:build:done": async ({ dir, pages, logger }) => {
+                const base = routing?.base ?? "/";
+                const trailingSlash = routing?.trailingSlash ?? "ignore";
+                // Every page Astro built, by its route from the host's root. Astro lists
+                // pages only, not endpoints such as a feed, so a dot in a page's last
+                // segment, as in `/v1.2`, is still a page.
+                const built = pages.map((page) => routeAs(`${normalizeBase(base)}${page.pathname.replace(/^\//, "")}`, trailingSlash));
+                const builtKeys = new Set(built.map(routeKey));
+                const files = rootFiles(rootSources(built, (route) => builtKeys.has(routeKey(route))));
+                fail(files.problems, "the site's robots.txt");
+                for (const note of files.notes)
+                    logger[note.level](note.text);
+                const out = fileURLToPath(dir);
+                if (files.sitemap !== undefined) {
+                    await writeFile(path.join(out, "sitemap.xml"), files.sitemap);
+                    logger.info(`wrote ${sitemapRoute(base)}`);
+                }
+                if (files.robots !== undefined) {
+                    await writeFile(path.join(out, "robots.txt"), files.robots);
+                    logger.info("wrote /robots.txt");
+                }
+                // The host's headers, from the projects that name its format.
+                const ownHeaders = path.join(publicDir, "_headers");
+                const headers = headersOutcome({
+                    rules: mergeRules(entries
+                        .filter((entry) => entry.project.consumer.headers === "netlify")
+                        .map((entry) => readHeaders(entry.siteRoot) ?? [])),
+                    base,
+                    own: existsSync(ownHeaders) ? readFileSync(ownHeaders, "utf8") : undefined,
+                });
+                if (headers.kind === "fail")
+                    throw new Error(`@ascribed/astro: ${headers.text}`);
+                if (headers.kind === "note")
+                    logger.info(headers.text);
+                if (headers.kind === "write") {
+                    await writeFile(path.join(out, "_headers"), headers.text);
+                    logger.info("wrote /_headers");
+                }
+                // Entries of one project publish at one base path: the first entry's copies go last, so they win.
+                for (const entry of [...entries].reverse()) {
+                    const folder = folderUnder(entry.project.consumer.basePath, base);
+                    const where = folder === "" ? "" : ` to ${folder}`;
+                    if (await copyPublishedFiles(entry.siteRoot, dir, folder))
+                        logger.info(`copied _ascribe/files/${where}`);
+                    if (entry.agentsRoot !== undefined &&
+                        (await copyAgentFiles(entry.agentsRoot, dir, folder)))
+                        logger.info(`copied llms.txt and each page's Markdown${where}`);
+                }
             },
         },
     };