@writedocs/generator 0.4.10 → 0.4.12

package/astro.config.mjs

@@ -36,6 +36,7 @@ import { remarkUnknownComponentFallback } from './src/lib/mdx-unknown-components
 import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
+import { report } from './src/lib/cli-report.js';
 import {
   loadDocsConfig,
   resolveCodeblockTheme,
@@ -105,7 +106,7 @@ const contentPublicDir = path.join(contentDir, 'public');
 // document-relative URLs isn't meaningful anyway.
 const siteUrl = resolveSiteUrl(docsConfig);
 if (!siteUrl) {
-  console.log('[writedocs] No writedocs.json "domain" set - skipping sitemap.xml generation.');
+  report('info', 'No "domain" set in writedocs.json, so no sitemap.xml was generated.');
 }
 
 /** Recursively lists every .md/.mdx file under `baseDir` (Node 20's
@@ -184,18 +185,18 @@ function singleSitemapFile() {
         const chunks = fs.readdirSync(outDir).filter((f) => /^sitemap-\d+\.xml$/.test(f));
         const target = path.join(outDir, 'sitemap.xml');
         if (chunks.length !== 1) {
-          console.log(`[writedocs] ${chunks.length} sitemap files generated - keeping sitemap-index.xml.`);
+          report('debug', `${chunks.length} sitemap files generated - keeping sitemap-index.xml.`);
           return;
         }
         if (fs.existsSync(target)) {
-          console.log('[writedocs] public/sitemap.xml exists - keeping it and the generated sitemap-index.xml.');
+          report('info', 'public/sitemap.xml exists, so it was kept - the generated sitemap is sitemap-index.xml.');
           return;
         }
         fs.renameSync(path.join(outDir, chunks[0]), target);
         fs.rmSync(path.join(outDir, 'sitemap-index.xml'), { force: true });
         // O próprio plugin acabou de logar "sitemap-index.xml created"; esta
         // linha diz o que de fato ficou no build.
-        console.log(`[writedocs] Replaced ${chunks[0]} + sitemap-index.xml with a single sitemap.xml.`);
+        report('debug', `Replaced ${chunks[0]} + sitemap-index.xml with a single sitemap.xml.`);
       },
     },
   };

package/bin/writedocs.js

@@ -8,6 +8,7 @@ import { runDev } from '../src/cli/dev.js';
 import { runBuild } from '../src/cli/build.js';
 import { runInit } from '../src/cli/init.js';
 import { requireBuildKey } from '../src/cli/build-auth.js';
+import { log, step, plural, color, CliExit, errorText } from '../src/cli/output.js';
 // O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
 // que a plataforma importa por `@writedocs/generator/config-schema` - e o que
 // faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
@@ -49,11 +50,13 @@ program
   .description('Start a local dev server with hot reload')
   .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
   .option('-p, --port <port>', 'port to run on')
+  .option('--verbose', "also print Astro's and Vite's own output")
   .action(async (dir, opts) => {
     await runDev({
       contentDir: path.resolve(process.cwd(), dir),
       packageRoot,
       port: opts.port,
+      verbose: Boolean(opts.verbose),
     });
   });
 
@@ -66,6 +69,7 @@ program
   .description('Build a static site into <dir>/dist')
   .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
   .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
+  .option('--verbose', "also print Astro's and Vite's own output")
   .action(async (dir, opts) => {
     const contentDir = path.resolve(process.cwd(), dir);
     // Project-scoped, not global: a .env sitting next to this project's own
@@ -75,7 +79,7 @@ program
     // environment - an explicit `export`/CI secret still wins over the file.
     dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
     await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
-    await runBuild({ contentDir, packageRoot });
+    await runBuild({ contentDir, packageRoot, verbose: Boolean(opts.verbose) });
   });
 
 program
@@ -91,10 +95,9 @@ program
     const configPath = path.join(contentDir, 'writedocs.json');
     if (!fs.existsSync(configPath)) {
       // Mesma mensagem que loadDocsConfig() ja da pro mesmo caso.
-      console.error(
-        `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
-      );
-      process.exit(1);
+      log.error(`No writedocs.json found in ${contentDir}`);
+      log.detail(color.dim('Run "writedocs init" to create one.'));
+      throw new CliExit(1);
     }
 
     const rawText = fs.readFileSync(configPath, 'utf-8');
@@ -109,15 +112,21 @@ program
       // A versao longa (linha, frase humana, sugestao) em vez da curta que o
       // `writedocs build` imprime: aqui o usuario pediu explicitamente um
       // diagnostico, e tem a tela inteira pra ele.
-      console.error(`[writedocs] ${configPath} failed validation:\n`);
-      console.error(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
-      console.error('');
+      log.error(
+        result.kind === 'invalid_json'
+          ? `${nomeArquivo} is not valid JSON`
+          : `${plural(result.issues.length, 'error')} in ${nomeArquivo}`
+      );
+      log.line();
+      log.line(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
+      log.line();
     }
 
     if (warnings.length > 0) {
-      console.error(`[writedocs] ${warnings.length} warning${warnings.length === 1 ? '' : 's'}:\n`);
-      console.error(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
-      console.error('');
+      log.warn(`${plural(warnings.length, 'warning')} in ${nomeArquivo}`);
+      log.line();
+      log.line(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
+      log.line();
     }
 
     // The pages: everything that would fail the build (errors) or build
@@ -128,27 +137,35 @@ program
     let content = null;
     if (!options.configOnly) {
       const { checkContent, formatContentIssues } = await import('../src/lib/content-check.js');
+      const checking = step('Checking pages');
       content = await checkContent(contentDir, result.kind === 'invalid_json' ? null : rawText);
+      checking.stop();
       if (content.errors.length > 0) {
-        console.error(`[writedocs] ${content.errors.length} error${content.errors.length === 1 ? '' : 's'} in the pages:\n`);
-        console.error(formatContentIssues(content.errors));
-        console.error('');
+        log.error(`${plural(content.errors.length, 'error')} in the pages`);
+        log.line();
+        log.line(formatContentIssues(content.errors));
+        log.line();
       }
       if (content.warnings.length > 0) {
-        console.error(`[writedocs] ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} in the pages:\n`);
-        console.error(formatContentIssues(content.warnings));
-        console.error('');
+        log.warn(`${plural(content.warnings.length, 'warning')} in the pages`);
+        log.line();
+        log.line(formatContentIssues(content.warnings));
+        log.line();
       }
     }
 
-    if (!result.ok || (content && content.errors.length > 0)) process.exit(1);
+    if (!result.ok || (content && content.errors.length > 0)) {
+      const total = (result.ok ? 0 : result.issues.length) + (content ? content.errors.length : 0);
+      log.error(`Not valid: ${plural(total, 'error')} to fix - the build would fail on these.`);
+      throw new CliExit(1);
+    }
     // Aviso nao invalida: um config so com avisos continua valido, e sai 0 -
     // o mesmo criterio que a plataforma usa pra marcar o projeto como `valid`.
-    console.log(`[writedocs] ${configPath} is valid.`);
+    log.success(`${nomeArquivo} is valid`);
     if (content) {
-      console.log(
-        `[writedocs] Checked ${content.pages} page${content.pages === 1 ? '' : 's'}: no errors` +
-          (content.warnings.length ? `, ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} above.` : '.')
+      log.success(
+        `Checked ${plural(content.pages, 'page')}: no errors` +
+          (content.warnings.length ? `, ${plural(content.warnings.length, 'warning')} above` : '')
       );
     }
   });
@@ -165,8 +182,8 @@ program
     // --mintlify is the only source today; the flag is still required so
     // the command reads the same once other tools are added.
     if (!options.mintlify && !options.docsJson) {
-      console.error('[writedocs] Say what to convert from: writedocs convert --mintlify [dir]');
-      process.exit(1);
+      log.error('Say what to convert from: writedocs convert --mintlify [dir]');
+      throw new CliExit(1);
     }
     const { runConvert } = await import('../src/cli/convert.js');
     await runConvert({
@@ -185,6 +202,8 @@ program
   });
 
 program.parseAsync(process.argv).catch((err) => {
-  console.error(`[writedocs] ${err.message}`);
+  // A command that already printed its own error throws CliExit.
+  if (err instanceof CliExit) process.exit(err.code);
+  log.error(errorText(err));
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/api-pages-output.js

@@ -0,0 +1,11 @@
+// What generateApiPages() did, as ✓ lines - shared by `dev` and `build`.
+import { log, plural, color } from './output.js';
+
+export function reportApiPages({ groups, pageSpecs }) {
+  for (const { group, src, operations } of groups) {
+    log.success(`Generated ${plural(operations, 'API page')} for "${group}" ${color.dim(`from ${src}`)}`);
+  }
+  for (const { spec, operations } of pageSpecs) {
+    log.success(`Read ${plural(operations, 'operation')} from ${spec} ${color.dim('(named by pages)')}`);
+  }
+}

package/src/cli/astro-output.js

@@ -0,0 +1,146 @@
+// Turns what Astro and Vite report (see astro-worker.js) into what the
+// writedocs CLI shows: an error becomes { where, message, hint } - the
+// author's file and line, and the reason in one sentence - instead of a
+// bundler error with a stack trace; a log line is either something the
+// author should see or noise to hide.
+import path from 'node:path';
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+export const stripAnsi = (text) => String(text ?? '').replace(ANSI, '');
+
+// Astro's formatted errors (core/messages/runtime.js formatErrorMessage)
+// append these sections after the message itself.
+const SECTION = /\n\s*(Stack trace|Hint|Error reference|Location|Caused by):/;
+
+function relativeTo(contentDir, file) {
+  if (!file) return null;
+  const clean = file.replace(/^file:\/\/\/?/, '').replace(/[?#].*$/, '');
+  const abs = path.resolve(clean);
+  const rel = path.relative(contentDir, abs);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/');
+}
+
+function position(line, column) {
+  if (!Number.isInteger(line) || line < 1) return '';
+  return Number.isInteger(column) && column > 0 ? `:${line}:${column}` : `:${line}`;
+}
+
+/** Everything an Astro/Vite error can say, as { where, message, hint }.
+ *  `input` is a serialized error (astro-worker.js serializeError) or the
+ *  text of an error log line. */
+export function describeError(input, contentDir) {
+  const error = typeof input === 'string' ? { message: input } : input ?? {};
+  let text = stripAnsi(error.message).replace(/\r/g, '');
+  let file = error.loc?.file ?? null;
+  let line = error.loc?.line;
+  let column = error.loc?.column;
+  let hint = error.hint ? stripAnsi(error.hint).trim() : null;
+  let name = error.name;
+
+  // A bundler failure wraps the real error:
+  //   Build failed with 1 error:
+  //
+  //   [plugin @mdx-js/rolldown] /abs/docs/page.mdx:undefined:undefined
+  //   MDXError: Expected a closing tag for `<Card>` (110:1-110:17)
+  //       at ...
+  const bundled = text.match(/^Build failed with \d+ errors?:\s*\n+([\s\S]*)$/);
+  if (bundled) {
+    const [head, ...rest] = bundled[1].split('\n');
+    const plugin = head.match(/^\[plugin [^\]]+\]\s+(.+?)(?::(\d+|undefined):(\d+|undefined))?\s*$/);
+    if (plugin) {
+      file = file ?? plugin[1];
+      if (plugin[2] && plugin[2] !== 'undefined') line = line ?? Number(plugin[2]);
+      if (plugin[3] && plugin[3] !== 'undefined') column = column ?? Number(plugin[3]);
+      text = rest.join('\n');
+    } else {
+      text = bundled[1];
+    }
+  }
+
+  // Astro's own sections: keep the hint, and take the file from the first
+  // stack frame when it's one of the author's files.
+  const sectionAt = text.search(SECTION);
+  if (sectionAt !== -1) {
+    const sections = text.slice(sectionAt);
+    text = text.slice(0, sectionAt);
+    const hintMatch = sections.match(/\n\s*Hint:\s*\n([\s\S]*?)(?=\n\s*(Stack trace|Error reference|Location|Caused by):|$)/);
+    if (hintMatch && !hint) hint = hintMatch[1].trim().replace(/\n\s+/g, ' ');
+    const frame = sections.match(/Stack trace:\s*\n\s*at (.+)/);
+    if (frame && !file) file = frame[1].trim();
+  }
+
+  // Stack frames and an "SomethingError: " prefix are noise here.
+  text = text
+    .split('\n')
+    .filter((l) => !/^\s+at\s/.test(l) && !/^\s*\[\.\.\.\] See full stack trace/.test(l))
+    .join('\n')
+    .trim();
+  const prefixed = text.match(/^([A-Z][A-Za-z]*Error|YAMLException):\s+([\s\S]*)$/);
+  if (prefixed) {
+    name = name && name !== 'Error' ? name : prefixed[1];
+    text = prefixed[2];
+  }
+  text = text.replace(/^\[writedocs\]\s*/, '');
+
+  // micromark/MDX put the position at the end: "(110:1-110:17)" or "(3:5)".
+  const pos = text.match(/\s*\((\d+):(\d+)(?:-\d+:\d+)?\)\s*$/);
+  if (pos) {
+    line = line ?? Number(pos[1]);
+    column = column ?? Number(pos[2]);
+    text = text.slice(0, pos.index);
+  }
+
+  if (name === 'YAMLException') text = `Frontmatter isn't valid YAML: ${text}`;
+
+  const rel = relativeTo(contentDir, file);
+  return {
+    where: rel ? `${rel}${position(line, column)}` : null,
+    message: text || 'Unknown error.',
+    hint: hint || null,
+    // The same error seen again - dev.js uses it to recall the file when
+    // a repeat of the error no longer names it.
+    key: `${text}|${position(line, column)}`,
+  };
+}
+
+/** A route Astro just wrote during a build ("  ├─ /docs/x/index.html"),
+ *  or null. */
+export function builtRoute(event) {
+  if (event.type !== 'astro-log' || event.level !== 'info') return null;
+  const match = stripAnsi(event.message).match(/^\s*[├└]─\s+(\S+)/);
+  return match ? match[1] : null;
+}
+
+/** A dev request log ("[404] /nope/ 18ms") as { status, url }, or null. */
+export function requestLog(event) {
+  if (event.type !== 'astro-log') return null;
+  const match = stripAnsi(event.message).match(/^\[(\d{3})\]\s+(?:\(rewrite\)\s+)?(?:[A-Z]+\s+)?(\S+)/);
+  return match ? { status: Number(match[1]), url: match[2] } : null;
+}
+
+/** An Astro/Vite warning worth showing the author: one about their own
+ *  files (it names a path inside the project), rewritten to relative
+ *  paths. Everything else - bundle sizes, dependency optimization, route
+ *  internals - is about writedocs itself, and stays hidden (--verbose shows
+ *  it). */
+export function authorWarning(event, contentDir) {
+  if (event.type !== 'astro-log' || event.level !== 'warn') return null;
+  const text = stripAnsi(event.message);
+  const variants = [contentDir, contentDir.split(path.sep).join('/'), contentDir.split('/').join('\\')];
+  if (!variants.some((v) => text.includes(v))) return null;
+  let out = text;
+  for (const v of variants) out = out.split(`${v}/`).join('').split(`${v}\\`).join('').split(v).join('.');
+  return out.trim();
+}
+
+/** One event as a plain line, for --verbose. */
+export function verboseLine(event) {
+  if (event.type === 'astro-log') {
+    const label = event.label && event.label !== 'SKIP_FORMAT' ? `[${event.label}] ` : '';
+    const level = event.level === 'warn' || event.level === 'error' ? `${event.level.toUpperCase()} ` : '';
+    return `${level}${label}${stripAnsi(event.message)}`;
+  }
+  if (event.type === 'raw') return stripAnsi(event.line);
+  return null;
+}

package/src/cli/astro-worker.js

@@ -0,0 +1,78 @@
+// Runs Astro for `writedocs dev` and `writedocs build`, in a process of its
+// own (spawned by run-astro.js). Astro is driven through its programmatic API
+// rather than its CLI binary, so that:
+//   - every Astro/Vite log line goes to lib/astro-log-destination.js, which
+//     forwards it to the writedocs CLI instead of printing it;
+//   - a fatal error comes back here as an Error object, sent to the CLI with
+//     its file/line/hint intact, not as pre-formatted terminal text;
+//   - none of the `astro` CLI's own behavior applies: its one-dev-server-per-
+//     root lock (every writedocs project shares one root, packageRoot, so two
+//     projects' `writedocs dev` would refuse each other), and its automatic
+//     "run in the background" mode when it detects an AI agent.
+//
+// Messages to the parent (process.send):
+//   { type: 'astro-log', level, label, message }  - from the log destination
+//   { type: 'ready', urls: { local, network } }     - dev server listening
+//   { type: 'done' }                                - build finished
+//   { type: 'fatal', error }                        - see serializeError()
+import path from 'node:path';
+import { build, dev } from 'astro';
+
+const command = process.argv[2];
+const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT;
+const port = process.env.WRITEDOCS_PORT ? Number(process.env.WRITEDOCS_PORT) : undefined;
+
+function send(message) {
+  if (typeof process.send === 'function' && process.connected) process.send(message);
+}
+
+function serializeError(err) {
+  if (!(err instanceof Error)) return { message: String(err) };
+  return {
+    name: err.name,
+    message: err.message,
+    hint: typeof err.hint === 'string' ? err.hint : undefined,
+    loc: err.loc && err.loc.file ? { file: err.loc.file, line: err.loc.line, column: err.loc.column } : undefined,
+    id: typeof err.id === 'string' ? err.id : undefined,
+    frame: typeof err.frame === 'string' ? err.frame : undefined,
+    stack: err.stack,
+    cause: err.cause ? serializeError(err.cause) : undefined,
+  };
+}
+
+async function fail(err) {
+  send({ type: 'fatal', error: serializeError(err) });
+  // Let the IPC message leave before exiting.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  process.exit(1);
+}
+
+process.on('uncaughtException', fail);
+process.on('unhandledRejection', fail);
+// The writedocs CLI went away (closed terminal, killed) - don't outlive it.
+process.on('disconnect', () => process.exit(0));
+
+const inlineConfig = {
+  root: packageRoot,
+  logLevel: 'info',
+  logger: { entrypoint: path.join(packageRoot, 'src', 'lib', 'astro-log-destination.js') },
+};
+
+try {
+  if (command === 'dev') {
+    const server = await dev({
+      ...inlineConfig,
+      ...(port ? { server: { port } } : {}),
+    });
+    send({ type: 'ready', urls: server.resolvedUrls ?? { local: [], network: [] } });
+  } else if (command === 'build') {
+    await build(inlineConfig);
+    send({ type: 'done' });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    process.exit(0);
+  } else {
+    throw new Error(`astro-worker: unknown command "${command}"`);
+  }
+} catch (err) {
+  await fail(err);
+}

package/src/cli/build-auth.js

@@ -15,16 +15,18 @@
  * See docs/dev/docs/deploy.mdx for how to deploy key-server/ and issue
  * keys, and key-server/README.md for the service's own endpoints.
  */
+import { log } from './output.js';
+
 export const EX_TEMPFAIL = 75;
 
 export async function requireBuildKey(providedKey) {
   const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
   if (!serverUrl) {
-    console.error('[writedocs] build is not available.');
+    log.error('build is not available.');
     process.exit(1);
   }
   if (!providedKey) {
-    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY).');
+    log.error('build requires a valid --key (or WRITEDOCS_API_KEY).');
     process.exit(1);
   }
 
@@ -47,12 +49,12 @@ export async function requireBuildKey(providedKey) {
     // Fails closed on a network error/timeout too, same as an explicit
     // rejection - an unreachable authorization server is not treated as
     // "no opinion, let it through".
-    console.error(`[writedocs] Could not reach the build authorization server: ${err.message}`);
+    log.error(`Could not reach the build authorization server: ${err.message}`);
     process.exit(EX_TEMPFAIL);
   }
 
   if (res.status >= 500) {
-    console.error(`[writedocs] The build authorization server failed (HTTP ${res.status}) - try again later.`);
+    log.error(`The build authorization server failed (HTTP ${res.status}) - try again later.`);
     process.exit(EX_TEMPFAIL);
   }
 
@@ -63,7 +65,7 @@ export async function requireBuildKey(providedKey) {
   }
 
   if (!valid) {
-    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY) - the server rejected this one.');
+    log.error('build requires a valid --key (or WRITEDOCS_API_KEY) - the server rejected this one.');
     process.exit(1);
   }
 }

package/src/cli/build.js

@@ -6,12 +6,88 @@ import { preflightCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-file.js';
 import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
+import { log, step, plural, duration, displayPath, formatProblems, color, CliExit } from './output.js';
+import { describeError, builtRoute, authorWarning, verboseLine } from './astro-output.js';
+import { reportApiPages } from './api-pages-output.js';
 
-export async function runBuild({ contentDir, packageRoot }) {
+export async function runBuild({ contentDir, packageRoot, verbose = false }) {
+  const started = Date.now();
   preflightCheck(contentDir);
-  await generateApiPages({ contentDir });
-  console.log(`[writedocs] Building ${contentDir} -> ${contentDir}/dist`);
-  await runAstro(['build', '--root', packageRoot], { packageRoot, contentDir });
+
+  // Collected while building, printed together at the end - a warning in
+  // the middle of a spinner is easy to miss.
+  const warnings = [];
+  const notes = [];
+  const seen = new Set();
+  const addWarning = (where, message) => {
+    const key = `${where ?? ''}\n${message}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    warnings.push({ where, message });
+  };
+
+  const api = await generateApiPages({ contentDir });
+  reportApiPages(api);
+  api.warnings.forEach((message) => addWarning(null, message));
+
+  const building = step('Building pages');
+  const buildStarted = Date.now();
+  let pages = 0;
+  let fatal = null;
+  const rawTail = [];
+  const { exited } = runAstro('build', {
+    packageRoot,
+    contentDir,
+    onEvent(event) {
+      if (verbose) {
+        const line = verboseLine(event);
+        if (line !== null) log.line(color.dim(line));
+      }
+      if (event.type === 'fatal') {
+        fatal = event.error;
+        return;
+      }
+      if (event.type === 'report') {
+        if (event.level === 'warn') addWarning(event.where, event.message);
+        else if (event.level === 'info' && !notes.includes(event.message)) notes.push(event.message);
+        return;
+      }
+      if (event.type === 'raw') {
+        rawTail.push(event.line);
+        if (rawTail.length > 40) rawTail.shift();
+        return;
+      }
+      const route = builtRoute(event);
+      if (route) {
+        if (route.endsWith('.html')) pages += 1;
+        building.update(`Building pages ${color.dim(`(${pages})`)}`);
+        return;
+      }
+      const warning = authorWarning(event, contentDir);
+      if (warning) addWarning(null, warning);
+    },
+  });
+  const code = await exited;
+
+  if (fatal || code !== 0) {
+    building.fail('Build failed');
+    if (fatal) {
+      const problem = describeError(fatal, contentDir);
+      log.line();
+      log.line(formatProblems([{ where: problem.where, message: problem.message }]));
+      if (problem.hint) log.line(`\n${color.dim(`  Hint: ${problem.hint}`)}`);
+      if (verbose && fatal.stack) log.line(`\n${color.dim(fatal.stack)}`);
+    } else if (rawTail.length) {
+      // No structured error (the worker itself crashed) - show what it printed.
+      log.line();
+      log.line(color.dim(rawTail.join('\n')));
+    }
+    log.line();
+    log.line(color.dim('Run "writedocs validate" to list every problem in the project at once.'));
+    throw new CliExit(1);
+  }
+  building.succeed(`Built ${plural(pages, 'page')} ${color.dim(`in ${duration(Date.now() - buildStarted)}`)}`);
+
   const distDir = path.join(contentDir, 'dist');
   // Astro just wrote its actual output to writedocsBuildStagingDir()
   // (astro.config.mjs's own `outDir`), not distDir directly - see that
@@ -34,7 +110,28 @@ export async function runBuild({ contentDir, packageRoot }) {
   // - this turns those into real instant edge redirects on hosts that read
   // a `_redirects` file (Cloudflare Pages, Netlify), purely additively.
   writeRedirectsFile(distDir, contentDir);
-  console.log('[writedocs] Indexing search...');
-  await runPagefind(distDir, { packageRoot });
-  console.log(`[writedocs] Done. Output written to ${contentDir}/dist`);
+
+  const indexing = step('Indexing search');
+  try {
+    await runPagefind(distDir, { packageRoot });
+  } catch (err) {
+    indexing.fail('Search indexing failed');
+    log.line();
+    log.line(color.dim(err.message));
+    throw new CliExit(1);
+  }
+  indexing.succeed('Indexed search');
+
+  if (warnings.length) {
+    log.line();
+    log.warn(plural(warnings.length, 'warning'));
+    log.line();
+    log.line(formatProblems(warnings));
+  }
+  if (notes.length) {
+    log.line();
+    notes.forEach((note) => log.info(note));
+  }
+  log.line();
+  log.success(`Done in ${duration(Date.now() - started)} ${color.dim('-')} site written to ${color.bold(displayPath(distDir))}`);
 }