@writedocs/generator 0.4.11 → 0.4.12

package/src/cli/convert.js

@@ -7,32 +7,33 @@ import path from 'node:path';
 import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/mintlify-convert.js';
 import { validateDocsConfig, formatValidationIssuesDetailed } from '../lib/config-schema.js';
 import { checkContent, formatContentIssues } from '../lib/content-check.js';
+import { log, step, plural, color, displayPath, CliExit } from './output.js';
 
 export async function runConvert({ contentDir, force = false, dryRun = false }) {
   const docsJsonPath = path.join(contentDir, 'docs.json');
   if (!fs.existsSync(docsJsonPath)) {
     const legacy = path.join(contentDir, 'mint.json');
     if (fs.existsSync(legacy)) {
-      console.error(
-        `[writedocs] Found mint.json, Mintlify's older config format. Run \`npx mint upgrade\` in ${contentDir} to turn it into docs.json, then run this again.`
-      );
+      log.error("Found mint.json, Mintlify's older config format.");
+      log.detail(color.dim(`Run "npx mint upgrade" in ${contentDir} to turn it into docs.json, then run this again.`));
     } else {
-      console.error(`[writedocs] No docs.json found in ${contentDir}.`);
+      log.error(`No docs.json found in ${contentDir}`);
     }
-    process.exit(1);
+    throw new CliExit(1);
   }
   const outPath = path.join(contentDir, 'writedocs.json');
   if (!dryRun && !force && fs.existsSync(outPath)) {
-    console.error(`[writedocs] ${outPath} already exists. Pass --force to overwrite it, or --dry-run to only see the result.`);
-    process.exit(1);
+    log.error(`${displayPath(outPath)} already exists.`);
+    log.detail(color.dim('Pass --force to overwrite it, or --dry-run to only see the result.'));
+    throw new CliExit(1);
   }
 
   let docs;
   try {
     docs = loadMintlifyConfig(docsJsonPath);
   } catch (err) {
-    console.error(`[writedocs] Couldn't read ${docsJsonPath}: ${err.message}`);
-    process.exit(1);
+    log.error(`Couldn't read ${displayPath(docsJsonPath)}: ${err.message}`);
+    throw new CliExit(1);
   }
 
   const { config, notes } = convertMintlifyConfig(docs);
@@ -42,41 +43,51 @@ export async function runConvert({ contentDir, force = false, dryRun = false })
   // converter bug, and writing it would only hand the author a broken file.
   const result = validateDocsConfig(text);
   if (!result.ok) {
-    console.error('[writedocs] The converted writedocs.json is not valid - this is a bug in the converter, please report it:\n');
-    console.error(formatValidationIssuesDetailed(result.issues));
-    console.error(`\n${text}`);
-    process.exit(1);
+    log.error('The converted writedocs.json is not valid - this is a bug in the converter, please report it:');
+    log.line();
+    log.line(formatValidationIssuesDetailed(result.issues));
+    log.line(`\n${text}`);
+    throw new CliExit(1);
   }
 
   if (dryRun) {
-    console.log(text);
+    log.line(text);
   } else {
     fs.writeFileSync(outPath, text);
-    console.log(`[writedocs] Converted ${path.basename(docsJsonPath)} -> ${outPath}`);
+    log.success(`Converted ${path.basename(docsJsonPath)} to ${color.bold(displayPath(outPath))}`);
   }
 
   if (notes.length) {
-    console.log(`\n[writedocs] ${notes.length} thing${notes.length === 1 ? '' : 's'} couldn't be carried over as-is:\n`);
-    console.log(formatNotes(notes));
+    log.line();
+    log.info(`${plural(notes.length, 'thing')} couldn't be carried over as-is:`);
+    log.line();
+    log.line(formatNotes(notes));
   }
 
   // The pages, checked against the converted config - what's left to fix
   // before the first build.
+  const checking = step('Checking pages');
   const content = await checkContent(contentDir, text);
+  checking.stop();
   if (content.errors.length) {
-    console.log(`\n[writedocs] ${content.errors.length} error${content.errors.length === 1 ? '' : 's'} in the pages - the build would fail on these:\n`);
-    console.log(formatContentIssues(content.errors));
+    log.line();
+    log.error(`${plural(content.errors.length, 'error')} in the pages - the build would fail on these:`);
+    log.line();
+    log.line(formatContentIssues(content.errors));
   }
   if (content.warnings.length) {
-    console.log(`\n[writedocs] ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} in the pages:\n`);
-    console.log(formatContentIssues(content.warnings));
+    log.line();
+    log.warn(`${plural(content.warnings.length, 'warning')} in the pages:`);
+    log.line();
+    log.line(formatContentIssues(content.warnings));
   }
-  console.log(
-    `\n[writedocs] Checked ${content.pages} page${content.pages === 1 ? '' : 's'}: ${content.errors.length} error${content.errors.length === 1 ? '' : 's'}, ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'}.`
-  );
+  log.line();
+  const summary = `Checked ${plural(content.pages, 'page')}: ${plural(content.errors.length, 'error')}, ${plural(content.warnings.length, 'warning')}`;
+  if (content.errors.length) log.error(summary);
+  else log.success(summary);
   if (!config.domain) {
-    console.log(
-      '[writedocs] Next: set "domain" in writedocs.json to your site\'s URL - it turns on sitemap.xml and absolute links for social previews. (Mintlify sets this in its dashboard, not docs.json.)'
+    log.info(
+      'Next: set "domain" in writedocs.json to your site\'s URL - it turns on sitemap.xml and absolute links for social previews. (Mintlify sets this in its dashboard, not docs.json.)'
     );
   }
 }

package/src/cli/dev-lock.js

@@ -0,0 +1,51 @@
+// One `writedocs dev` at a time. Every project is served with the writedocs
+// package itself as Astro's root (see run-astro.js), so two previews running
+// at once - even of different projects - share Astro's dev state in
+// <packageRoot>/.astro and overwrite each other's pages. The `astro` CLI
+// has its own lock for this, but writedocs drives Astro through its API
+// (astro-worker.js), which doesn't; this is the same guard, with a message
+// that makes sense to a writedocs author.
+import fs from 'node:fs';
+import path from 'node:path';
+
+function lockPath(packageRoot) {
+  return path.join(packageRoot, '.astro', 'writedocs-dev.json');
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: it exists, it's just not ours to signal.
+    return err.code === 'EPERM';
+  }
+}
+
+/** The preview already running - { pid, contentDir, url } - or null. A
+ *  lock left behind by a preview that didn't exit cleanly is ignored. */
+export function runningPreview(packageRoot) {
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath(packageRoot), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!Number.isInteger(lock?.pid) || lock.pid === process.pid || !isAlive(lock.pid)) return null;
+  return lock;
+}
+
+export function writeLock(packageRoot, data) {
+  const file = lockPath(packageRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ pid: process.pid, ...data }, null, 2));
+}
+
+/** Removes the lock, if it's this process's. */
+export function removeLock(packageRoot) {
+  const file = lockPath(packageRoot);
+  try {
+    const lock = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (lock.pid === process.pid) fs.rmSync(file, { force: true });
+  } catch {}
+}

package/src/cli/dev.js

@@ -1,12 +1,164 @@
 import { runAstro } from './run-astro.js';
 import { preflightCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
+import { log, step, duration, formatProblems, color, CliExit } from './output.js';
+import { describeError, requestLog, authorWarning, verboseLine, stripAnsi } from './astro-output.js';
+import { reportApiPages } from './api-pages-output.js';
+import { runningPreview, writeLock, removeLock } from './dev-lock.js';
 
-export async function runDev({ contentDir, packageRoot, port }) {
+// The same problem tends to arrive more than once in a row - Vite and
+// Astro each log a failed page, and a page compiles for more than one
+// environment. Within this window, a repeat is dropped.
+const REPEAT_WINDOW_MS = 2000;
+
+export async function runDev({ contentDir, packageRoot, port, verbose = false }) {
+  const started = Date.now();
   preflightCheck(contentDir);
-  await generateApiPages({ contentDir });
-  const args = ['dev', '--root', packageRoot];
-  if (port) args.push('--port', String(port));
-  console.log(`[writedocs] Serving ${contentDir}`);
-  await runAstro(args, { packageRoot, contentDir });
+  const other = runningPreview(packageRoot);
+  if (other) {
+    log.error(`Another writedocs preview is already running${other.url ? ` at ${other.url}` : ''}.`);
+    log.detail(
+      color.dim(
+        `It's serving ${other.contentDir}. Stop it first (Ctrl+C in its terminal) - two previews at once overwrite each other's pages.`
+      )
+    );
+    throw new CliExit(1);
+  }
+  writeLock(packageRoot, { contentDir, url: null });
+  process.on('exit', () => removeLock(packageRoot));
+
+  const api = await generateApiPages({ contentDir });
+  reportApiPages(api);
+  api.warnings.forEach((message) => log.warn(message));
+
+  const starting = step('Starting local preview');
+  let ready = false;
+
+  const lastShown = new Map();
+  const once = (key, print) => {
+    const now = Date.now();
+    if (now - (lastShown.get(key) ?? 0) < REPEAT_WINDOW_MS) return;
+    lastShown.set(key, now);
+    print();
+  };
+  const oneLine = (where, message) => (where ? `${color.bold(where)}  ${message}` : message);
+
+  // A failed page is logged twice - Vite's error (message only) and then
+  // Astro's (message plus the file). Errors wait a moment so the two can
+  // be merged into one line that names the file.
+  // When the same page fails again, only the first report of it named the
+  // file: later ones point at the MDX compiler instead. The file each
+  // error was last seen in is remembered here, by the error itself.
+  const pendingErrors = new Map();
+  const knownWhere = new Map();
+  const showError = (problem) => {
+    if (problem.where) knownWhere.set(problem.key, problem.where);
+    else if (knownWhere.has(problem.key)) problem = { ...problem, where: knownWhere.get(problem.key) };
+    const existing = pendingErrors.get(problem.message);
+    if (existing) {
+      if (!existing.problem.where && problem.where) existing.problem = problem;
+      return;
+    }
+    const entry = { problem };
+    entry.timer = setTimeout(() => {
+      pendingErrors.delete(problem.message);
+      const { where, message, hint } = entry.problem;
+      once(`error\n${where}\n${message}`, () => {
+        log.error(oneLine(where, message));
+        if (hint) log.detail(color.dim(`Hint: ${hint}`));
+      });
+    }, 150);
+    pendingErrors.set(problem.message, entry);
+  };
+
+  let fatal = null;
+  const rawTail = [];
+  const { child, exited } = runAstro('dev', {
+    packageRoot,
+    contentDir,
+    port,
+    onEvent(event) {
+      if (verbose) {
+        const line = verboseLine(event);
+        if (line !== null) log.line(color.dim(line));
+      }
+      switch (event.type) {
+        case 'ready': {
+          ready = true;
+          starting.succeed(`Preview ready ${color.dim(`in ${duration(Date.now() - started)}`)}`);
+          const [local] = event.urls?.local ?? [];
+          writeLock(packageRoot, { contentDir, url: local ?? null });
+          const wanted = Number(port ?? 4321);
+          const actual = local ? Number(new URL(local).port) : wanted;
+          log.line();
+          log.line(`  ${color.bold('Local:')}  ${color.cyan(local ?? `http://localhost:${wanted}/`)}`);
+          if (actual !== wanted) log.line(color.dim(`          Port ${wanted} was in use, so the preview is on ${actual}.`));
+          log.line();
+          log.line(color.dim('  Edit any page and the preview updates. Press Ctrl+C to stop.'));
+          log.line();
+          return;
+        }
+        case 'fatal':
+          fatal = event.error;
+          return;
+        case 'report':
+          // 'info' notes are about the build (sitemap and the like), not
+          // the preview.
+          if (event.level === 'warn') once(`warn\n${event.where}\n${event.message}`, () => log.warn(oneLine(event.where, event.message)));
+          return;
+        case 'raw':
+          rawTail.push(event.line);
+          if (rawTail.length > 40) rawTail.shift();
+          return;
+        case 'astro-log': {
+          if (event.level === 'error') {
+            showError(describeError(stripAnsi(event.message), contentDir));
+            return;
+          }
+          const request = requestLog(event);
+          // A missing page is worth knowing about (a broken link, a typo in
+          // the navigation); a missing favicon or source map isn't.
+          if (request?.status === 404 && !/\.[a-z0-9]+$/i.test(request.url.split('?')[0])) {
+            once(`404\n${request.url}`, () => log.warn(`${color.bold(request.url)}  No page at this address (404).`));
+            return;
+          }
+          const warning = authorWarning(event, contentDir);
+          if (warning) once(`warn\n${warning}`, () => log.warn(warning));
+          return;
+        }
+      }
+    },
+  });
+
+  // Ctrl+C: stop the server quietly. (The child gets the same signal from
+  // the terminal; killing it here covers the cases where it doesn't.) A
+  // second Ctrl+C doesn't wait for it.
+  let stopping = false;
+  const stop = () => {
+    if (stopping) process.exit(130);
+    stopping = true;
+    child.kill();
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+
+  const code = await exited;
+  if (stopping) {
+    if (ready) log.line(color.dim('Preview stopped.'));
+    return;
+  }
+  // The server never stops on its own - getting here is a failure.
+  if (!ready) starting.fail('Could not start the local preview');
+  else log.error('The local preview stopped unexpectedly.');
+  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) {
+    log.line();
+    log.line(color.dim(rawTail.join('\n')));
+  }
+  throw new CliExit(code || 1);
 }

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

@@ -235,7 +235,7 @@ function collectOpenApiGroups(navigation) {
  *  in the same writedocs.json never collide with each other on disk, exactly
  *  as they won't collide in the URL space either (both keyed off the
  *  same `path` value). */
-async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides }) {
+async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides, summary }) {
   const pathPrefix = normalizePathPrefix(group.openapi.path);
   const specPath = path.resolve(contentDir, group.openapi.src);
   if (!fs.existsSync(specPath)) {
@@ -245,7 +245,6 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
     );
   }
 
-  console.log(`[writedocs] Parsing OpenAPI spec for "${group.group}": ${group.openapi.src}`);
   const spec = await SwaggerParser.dereference(specPath);
   const operations = buildOperations(spec);
 
@@ -293,7 +292,7 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
   }
 
   fs.writeFileSync(path.join(openapiOutDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
-  console.log(`[writedocs] Generated ${operations.length} API operation page(s) for "${group.group}"`);
+  summary.groups.push({ group: group.group, src: group.openapi.src, operations: operations.length });
 }
 
 /**
@@ -325,8 +324,13 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
  * No-ops (after clearing any stale output from a previous run) if
  * writedocs.json's navigation has no openapi groups at all - most sites don't
  * have one.
+ *
+ * Prints nothing: returns what it did, for the CLI to report -
+ * { groups: [{ group, src, operations }], pageSpecs: [{ spec, operations }],
+ *   warnings: [message] }.
  */
 export async function generateApiPages({ contentDir }) {
+  const summary = { groups: [], pageSpecs: [], warnings: [] };
   const writedocsJsonPath = path.join(contentDir, 'writedocs.json');
   const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
   const openapiOutDir = path.join(writedocsTempDir(contentDir), 'openapi');
@@ -335,7 +339,7 @@ export async function generateApiPages({ contentDir }) {
   try {
     config = JSON.parse(fs.readFileSync(writedocsJsonPath, 'utf-8'));
   } catch {
-    return; // preflightCheck() (run first, see dev.js/build.js) already reports this
+    return summary; // preflightCheck() (run first, see dev.js/build.js) already reports this
   }
 
   // Always start from a clean slate: a group's `path` (or the group
@@ -362,10 +366,11 @@ export async function generateApiPages({ contentDir }) {
 
   const overrides = findHandWrittenOverrides(contentDir);
   for (const group of groups) {
-    await generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides });
+    await generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides, summary });
   }
 
-  await parsePageSpecs({ contentDir, openapiOutDir, groupSpecs: groups.map((g) => path.resolve(contentDir, g.openapi.src)) });
+  await parsePageSpecs({ contentDir, openapiOutDir, groupSpecs: groups.map((g) => path.resolve(contentDir, g.openapi.src)), summary });
+  return summary;
 }
 
 /** Mintlify's page-level form, `openapi: "/spec.json METHOD /path"`: the
@@ -376,7 +381,7 @@ export async function generateApiPages({ contentDir }) {
  *  pages are generated - the pages that name the spec are the pages. A
  *  spec that's missing or doesn't parse is a warning, not a build failure:
  *  its pages show the playground's own "no operation found" notice. */
-async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs }) {
+async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs, summary }) {
   const specs = new Set();
   for (const rel of findAllPages(contentDir)) {
     let data;
@@ -392,14 +397,14 @@ async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs }) {
     const specPath = path.resolve(contentDir, spec);
     if (groupSpecs.includes(specPath)) continue;
     if (!fs.existsSync(specPath)) {
-      console.warn(`[writedocs] Pages name the OpenAPI spec "${spec}", which doesn't exist - their API playground shows a notice instead.`);
+      summary.warnings.push(`Pages name the OpenAPI spec "${spec}", which doesn't exist - their API playground shows a notice instead.`);
       continue;
     }
     let operations;
     try {
       operations = buildOperations(await SwaggerParser.dereference(specPath));
     } catch (err) {
-      console.warn(`[writedocs] Couldn't parse the OpenAPI spec "${spec}" that pages name: ${err.message}`);
+      summary.warnings.push(`Couldn't parse the OpenAPI spec "${spec}" that pages name: ${err.message}`);
       continue;
     }
     const outDir = path.join(openapiOutDir, '_pages', specDirName(spec), 'operations');
@@ -407,6 +412,6 @@ async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs }) {
     for (const operation of operations) {
       fs.writeFileSync(path.join(outDir, operationFileName(operation.method, operation.path)), JSON.stringify(operation, null, 2));
     }
-    console.log(`[writedocs] Parsed OpenAPI spec "${spec}" for the pages that name it (${operations.length} operations)`);
+    summary.pageSpecs.push({ spec, operations: operations.length });
   }
 }

package/src/cli/init.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { log, color } from './output.js';
 
 const WRITEDOCS_JSON = {
   name: 'My Docs',
@@ -59,23 +60,24 @@ export async function runInit({ targetDir }) {
 
   const configPath = path.join(targetDir, 'writedocs.json');
   if (fs.existsSync(configPath)) {
-    console.error(`[writedocs] writedocs.json already exists in ${targetDir}, skipping.`);
+    log.warn('writedocs.json already exists - left as it is.');
   } else {
     fs.writeFileSync(configPath, JSON.stringify(WRITEDOCS_JSON, null, 2) + '\n');
-    console.log(`[writedocs] Created writedocs.json`);
+    log.success('Created writedocs.json');
   }
 
   const indexPath = path.join(targetDir, 'index.mdx');
   if (!fs.existsSync(indexPath)) {
     fs.writeFileSync(indexPath, INDEX_MDX);
-    console.log(`[writedocs] Created index.mdx`);
+    log.success('Created index.mdx');
   }
 
   const gsPath = path.join(targetDir, 'docs', 'getting-started.mdx');
   if (!fs.existsSync(gsPath)) {
     fs.writeFileSync(gsPath, GETTING_STARTED_MDX);
-    console.log(`[writedocs] Created docs/getting-started.mdx`);
+    log.success('Created docs/getting-started.mdx');
   }
 
-  console.log(`\n[writedocs] Ready. Run "writedocs dev" to preview your site.`);
+  log.line();
+  log.line(`Ready. Run ${color.bold('writedocs dev')} to preview your site.`);
 }

package/src/cli/output.js

@@ -0,0 +1,160 @@
+// The writedocs CLI's own terminal output: every command prints through
+// these helpers, so they all read the same way - a ✓/✗/⚠ line per step, and
+// problems as "file:line  message" - and nothing Astro, Vite or Node prints
+// on their own reaches the terminal (see run-astro.js, which collects all of
+// that as events instead).
+//
+// Colors and the spinner only on an interactive terminal. In CI or a log
+// file (not a TTY), every line is plain text and a step prints once, when
+// it finishes. NO_COLOR turns colors off; FORCE_COLOR turns them on.
+import path from 'node:path';
+
+const stream = process.stdout;
+// Output piped into something that stopped reading (`writedocs build | head`):
+// nothing more can be shown, so stop instead of crashing on EPIPE.
+stream.on('error', (err) => {
+  if (err.code === 'EPIPE') process.exit(0);
+  throw err;
+});
+const interactive = Boolean(stream.isTTY) && process.env.TERM !== 'dumb' && !process.env.CI;
+const useColor =
+  process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0'
+    ? true
+    : process.env.NO_COLOR === undefined && interactive;
+
+const paint = (open, close) => (text) => (useColor ? `\x1b[${open}m${text}\x1b[${close}m` : String(text));
+export const color = {
+  bold: paint(1, 22),
+  dim: paint(2, 22),
+  red: paint(31, 39),
+  green: paint(32, 39),
+  yellow: paint(33, 39),
+  cyan: paint(36, 39),
+};
+
+const symbols = {
+  success: color.green('✓'),
+  error: color.red('✗'),
+  warn: color.yellow('⚠'),
+  info: color.cyan('ℹ'),
+};
+
+// One spinner at a time; anything printed while it spins clears its line
+// first and redraws it after.
+let activeSpinner = null;
+
+function writeLine(text = '') {
+  if (activeSpinner) activeSpinner.clear();
+  stream.write(`${text}\n`);
+  if (activeSpinner) activeSpinner.render();
+}
+
+export const log = {
+  line: writeLine,
+  success: (text) => writeLine(`${symbols.success} ${text}`),
+  error: (text) => writeLine(`${symbols.error} ${text}`),
+  warn: (text) => writeLine(`${symbols.warn} ${text}`),
+  info: (text) => writeLine(`${symbols.info} ${text}`),
+  // Text under a ✓/✗ line, indented to line up with it.
+  detail: (text) => writeLine(indent(text, 2)),
+};
+
+export function indent(text, spaces) {
+  const pad = ' '.repeat(spaces);
+  return String(text)
+    .split('\n')
+    .map((line) => (line ? pad + line : line))
+    .join('\n');
+}
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** A step in progress: a spinner with `text` on a terminal, nothing
+ *  elsewhere, until it ends with succeed()/fail()/stop(). */
+export function step(text) {
+  let current = text;
+  let frame = 0;
+  let timer = null;
+  const spinner = {
+    clear() {
+      stream.write('\r\x1b[2K');
+    },
+    render() {
+      stream.write(`\r\x1b[2K${color.cyan(FRAMES[frame])} ${current}`);
+    },
+  };
+  if (interactive) {
+    activeSpinner = spinner;
+    spinner.render();
+    timer = setInterval(() => {
+      frame = (frame + 1) % FRAMES.length;
+      spinner.render();
+    }, 80);
+    timer.unref?.();
+  }
+  const end = () => {
+    if (timer) clearInterval(timer);
+    if (activeSpinner === spinner) {
+      spinner.clear();
+      activeSpinner = null;
+    }
+  };
+  return {
+    update(next) {
+      current = next;
+      if (activeSpinner === spinner) spinner.render();
+    },
+    succeed(done = current) {
+      end();
+      log.success(done);
+    },
+    fail(done = current) {
+      end();
+      log.error(done);
+    },
+    stop() {
+      end();
+    },
+  };
+}
+
+/** Thrown by a command that already printed why it failed: bin/writedocs.js
+ *  exits with `code` without printing anything more. */
+export class CliExit extends Error {
+  constructor(code = 1) {
+    super(`exit ${code}`);
+    this.code = code;
+  }
+}
+
+/** The message of an error nobody formatted - a thrown Error's text,
+ *  without the "[writedocs] " prefix older messages carry. */
+export function errorText(err) {
+  return String(err?.message ?? err).replace(/^\[writedocs\]\s*/, '');
+}
+
+export function plural(count, word, many = `${word}s`) {
+  return `${count} ${count === 1 ? word : many}`;
+}
+
+export function duration(ms) {
+  return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** A path as the author would type it: relative to the current directory
+ *  when it's inside it, with forward slashes; absolute otherwise. */
+export function displayPath(target) {
+  const rel = path.relative(process.cwd(), target);
+  if (rel === '') return '.';
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return target;
+  return rel.split(path.sep).join('/');
+}
+
+/** Problems as "file:line" on one line and the message indented under
+ *  it - the same shape `writedocs validate` uses. `items`: { where?,
+ *  message } with `where` already "file:line" (or empty). */
+export function formatProblems(items) {
+  return items
+    .map(({ where, message }) => (where ? `  ${color.bold(where)}\n${indent(message, 4)}` : indent(message, 2)))
+    .join('\n\n');
+}

package/src/cli/preflight.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { log, color, CliExit } from './output.js';
 
 /**
  * Fast, dependency-light sanity check that runs before handing off to
@@ -17,19 +18,21 @@ export function preflightCheck(contentDir) {
     // that's a one-line fix rather than a real missing-config problem.
     const legacyConfigPath = path.join(contentDir, 'docs.json');
     if (fs.existsSync(legacyConfigPath)) {
-      console.error(`[writedocs] Found docs.json in ${contentDir}, but the config file is now named writedocs.json.`);
-      console.error(`[writedocs] Rename it: mv docs.json writedocs.json`);
-      process.exit(1);
+      log.error(`Found docs.json in ${contentDir}, but writedocs reads writedocs.json.`);
+      log.detail(color.dim('A Mintlify project? Run "writedocs convert --mintlify" to create writedocs.json from it.'));
+      log.detail(color.dim('An older writedocs project? Rename docs.json to writedocs.json.'));
+      throw new CliExit(1);
     }
-    console.error(`[writedocs] No writedocs.json found in ${contentDir}`);
-    console.error(`[writedocs] Run "writedocs init" to create 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);
   }
   try {
     JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   } catch (err) {
-    console.error(`[writedocs] writedocs.json is not valid JSON: ${err.message}`);
-    process.exit(1);
+    log.error(`writedocs.json is not valid JSON: ${err.message}`);
+    log.detail(color.dim('Run "writedocs validate" to see where.'));
+    throw new CliExit(1);
   }
   // No docs/-folder check here: docs/ isn't a required directory - a page
   // can live anywhere in the project (see findAllPages() in