@writedocs/generator 0.7.1 → 0.7.3

package/astro.config.mjs

@@ -143,26 +143,33 @@ function walkMdFiles(baseDir) {
 function collectNoindexIds(rootContentDir) {
   const generatedDocsDir = path.join(writedocsTempDir(rootContentDir), 'generated-docs');
   const ids = new Set();
+  // Whether some page is served at "/" itself. When none is, "/" is the
+  // redirect-only route [...slug].astro synthesizes (noindex, pointing at
+  // the first page) - which doesn't belong in the sitemap either.
+  let rootIsPage = false;
 
   for (const relativeId of findAllPages(rootContentDir)) {
     const file = path.join(rootContentDir, relativeId);
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    const pageId = normalizeEntryId(data?.slug ?? relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, ''));
+    if (pageId === 'index') rootIsPage = true;
     // Top-level `noindex` is Mintlify's spelling, and a Mintlify `hidden`
     // page is noindexed too - content.config.ts folds both into
     // `seo.noindex` the same way (an explicit value wins).
     // A frontmatter `url` page's route only redirects to that link, so it
     // doesn't belong in the sitemap either.
     if (!(data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && !data?.url) continue;
-    const fallbackId = relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
-    ids.add(normalizeEntryId(data.slug ?? fallbackId));
+    ids.add(pageId);
   }
   // Generated OpenAPI stub pages always set an explicit `slug` (see
   // generate-api-pages.js) - there's no file-path-derived id to fall back
   // to the way there is for a hand-written page.
   for (const file of walkMdFiles(generatedDocsDir)) {
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    if (data?.slug && normalizeEntryId(data.slug) === 'index') rootIsPage = true;
     if ((data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && data.slug) ids.add(normalizeEntryId(data.slug));
   }
+  if (!rootIsPage) ids.add('index');
   return ids;
 }
 
@@ -513,8 +520,7 @@ export default defineConfig({
         // from such a file never finds a package.json named "writedocs",
         // so self-reference fails and Vite reports the bare specifier as
         // unresolvable ("Rolldown failed to resolve import
-        // 'writedocs/components'"). See BUG.md for the full writeup this
-        // fix comes from.
+        // 'writedocs/components'").
         // This alias bypasses self-reference resolution entirely for
         // that one specifier - Vite's alias matching is a plain string
         // match against the specifier itself, independent of which file

package/bin/writedocs.js

@@ -9,6 +9,8 @@ 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, stopActiveStep } from '../src/cli/output.js';
+import { startUpdateCheck, showUpdateNotice } from '../src/cli/update-check.js';
+import { readConfigText } from '../src/lib/config-file.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
@@ -37,13 +39,21 @@ const packageRoot = path.resolve(__dirname, '..');
 // package.json). `writedocs --version` should always reflect what actually
 // got published, not whatever this string happened to say at the time this
 // line was last hand-edited.
-const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+const { name: packageName, version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
 
 const program = new Command();
 program
   .name('writedocs')
   .description('Static site generator for writedocs.json + MDX')
-  .version(version);
+  .version(version)
+  // The built-in `help <command>` prints any command's usage, hidden ones
+  // included - replaced by the `help` command at the bottom of this file.
+  .helpCommand(false)
+  // Every command checks for a newer writedocs (from a cache - see
+  // src/cli/update-check.js); the notice prints after the command's output.
+  .hook('preAction', (_program, command) => {
+    startUpdateCheck({ command: command.name(), name: packageName, version, packageRoot });
+  });
 
 program
   .command('dev')
@@ -66,6 +76,9 @@ program
   // src/cli/build-auth.js for the second layer: even someone who knows the
   // command exists still can't run it without the right key.
   .command('build', { hidden: true })
+  // `build --help` prints the general help, which doesn't list it: hidden
+  // means not described anywhere (see the `help` command at the bottom too).
+  .configureHelp({ formatHelp: () => program.helpInformation() })
   .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)')
@@ -73,8 +86,8 @@ program
   .action(async (dir, opts) => {
     const contentDir = path.resolve(process.cwd(), dir);
     // Project-scoped, not global: a .env sitting next to this project's own
-    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
-    // up automatically, so build doesn't need those exported by hand every
+    // writedocs.json (WRITEDOCS_API_KEY) is picked up automatically, so
+    // build doesn't need it exported by hand every
     // session. dotenv never overwrites a var already set in the real
     // environment - an explicit `export`/CI secret still wins over the file.
     dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
@@ -100,7 +113,7 @@ program
       throw new CliExit(1);
     }
 
-    const rawText = fs.readFileSync(configPath, 'utf-8');
+    const rawText = readConfigText(contentDir);
     const result = validateDocsConfig(rawText);
     // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
     // de proposito (tornar strict quebraria configs existentes), entao o Zod
@@ -180,7 +193,7 @@ program
     const contentDir = path.resolve(process.cwd(), dir);
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
-    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const configText = readConfigText(contentDir);
     const checking = step('Checking links');
     // Generated OpenAPI pages are link targets too - same step dev/build run.
     const { generateApiPages } = await import('../src/cli/generate-api-pages.js');
@@ -215,7 +228,7 @@ program
     const contentDir = path.resolve(process.cwd(), dir);
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
-    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const configText = readConfigText(contentDir);
     const checking = step('Checking accessibility');
     const { checkAccessibility } = await import('../src/lib/a11y-check.js');
     const { formatContentIssues } = await import('../src/lib/content-check.js');
@@ -246,8 +259,10 @@ program
   .option('--force', 'overwrite an existing writedocs.json')
   .option('--dry-run', 'print the converted writedocs.json instead of writing it')
   .action(async (dir, options) => {
-    const mintlify = options.mintlify || options.docsJson;
-    const legacy = options.writedocs || options.configJson;
+    // Commander camel-cases only on hyphens: `--docs.json` is stored under
+    // the key "docs.json", not `docsJson`.
+    const mintlify = options.mintlify || options['docs.json'];
+    const legacy = options.writedocs || options['config.json'];
     if (mintlify === legacy) {
       log.error(
         mintlify
@@ -265,6 +280,14 @@ program
     });
   });
 
+program
+  .command('update')
+  .description('Update writedocs to the latest version')
+  .action(async () => {
+    const { runUpdate } = await import('../src/cli/update.js');
+    await runUpdate({ name: packageName, version, packageRoot });
+  });
+
 program
   .command('init')
   .description('Scaffold a writedocs.json and starter docs/ folder')
@@ -273,10 +296,25 @@ program
     await runInit({ targetDir: path.resolve(process.cwd(), dir) });
   });
 
-program.parseAsync(process.argv).catch((err) => {
-  // A command that already printed its own error throws CliExit.
-  stopActiveStep();
-  if (err instanceof CliExit) process.exit(err.code);
-  log.error(errorText(err));
-  process.exit(1);
-});
+// `writedocs help [command]` - commander's own, except that a hidden command
+// (`build`) gets the general help, like a name that isn't a command at all.
+const HIDDEN_COMMANDS = new Set(['build']);
+program
+  .command('help')
+  .description('display help for command')
+  .argument('[command]')
+  .action((name) => {
+    const command = name && !HIDDEN_COMMANDS.has(name) ? program.commands.find((c) => c.name() === name) : undefined;
+    (command ?? program).help();
+  });
+
+program
+  .parseAsync(process.argv)
+  .then(showUpdateNotice)
+  .catch((err) => {
+    stopActiveStep();
+    // A command that already printed its own error throws CliExit.
+    if (!(err instanceof CliExit)) log.error(errorText(err));
+    showUpdateNotice();
+    process.exit(err instanceof CliExit ? err.code : 1);
+  });

package/package.json

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

package/src/cli/build-auth.js

@@ -1,8 +1,8 @@
 /**
  * `writedocs build` produces the artifact that actually gets deployed, so
  * unlike `dev`/`init` it isn't freely runnable by anyone who installs the
- * package - it's gated behind a key that a separate service (`key-server/`
- * in this repo) actually decides the validity of.
+ * package - it's gated behind a key that a separate service
+ * (writedocs-key-server, a sibling repo) actually decides the validity of.
  *
  * This deliberately isn't a local check. An earlier version compared the
  * supplied key against an env var set on the same machine
@@ -12,19 +12,26 @@
  * actually holds the set of issued keys means a key's validity is decided
  * by whoever runs that server, not by whoever is running `build`.
  *
- * 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.
+ * See docs/dev/docs/deploy.mdx for how to deploy writedocs-key-server and
+ * issue keys, and that repo's own README for the service's endpoints.
  */
 import { log } from './output.js';
 
 export const EX_TEMPFAIL = 75;
 
+/** The authorization server every `build` asks. Fixed in the code, with no
+ *  environment override: when the URL came from WRITEDOCS_KEY_SERVER_URL,
+ *  anyone could point it at a 3-line server that answers
+ *  `{ "valid": true }` and build without a key. Tests and CI use a real
+ *  key instead (the WRITEDOCS_API_KEY secret - see
+ *  scripts/smoke-installed-cli.sh). Honest limit: the source ships with the
+ *  package, so someone willing to edit it can still remove this check - it
+ *  raises the bar, it isn't a lock. Real protection is what the platform
+ *  does with the output. */
+export const KEY_SERVER_URL = 'https://proxy.writechoice.io:8787';
+
 export async function requireBuildKey(providedKey) {
-  const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
-  if (!serverUrl) {
-    log.error('build is not available.');
-    process.exit(1);
-  }
+  const serverUrl = KEY_SERVER_URL;
   if (!providedKey) {
     log.error('build requires a valid --key (or WRITEDOCS_API_KEY).');
     process.exit(1);

package/src/cli/build.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { runAstro } from './run-astro.js';
 import { runPagefind } from './run-pagefind.js';
-import { preflightCheck } from './preflight.js';
+import { preflightCheck, sameDriveCheck, writableInstallCheck } 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';
@@ -13,6 +13,7 @@ import { reportApiPages } from './api-pages-output.js';
 export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   const started = Date.now();
   preflightCheck(contentDir);
+  writableInstallCheck(packageRoot);
 
   // Collected while building, printed together at the end - a warning in
   // the middle of a spinner is easy to miss.
@@ -27,6 +28,7 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   };
 
   const api = await generateApiPages({ contentDir });
+  sameDriveCheck(contentDir, packageRoot, { generatedPages: api.groups.length > 0 });
   reportApiPages(api);
   api.warnings.forEach((message) => addWarning(null, message));
 

package/src/cli/convert.js

@@ -10,7 +10,7 @@ import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/m
 import { loadLegacyConfig, convertLegacyConfig } from '../lib/writedocs-legacy-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';
+import { log, step, plural, color, displayPath, CliExit, logToStderr } from './output.js';
 
 const SOURCES = {
   mintlify: {
@@ -39,6 +39,10 @@ const SOURCES = {
 };
 
 export async function runConvert({ source = 'mintlify', contentDir, force = false, dryRun = false }) {
+  // --dry-run's stdout is the converted writedocs.json and nothing else, so
+  // `writedocs convert --dry-run > writedocs.json` works; the notes and the
+  // page check go to stderr.
+  if (dryRun) logToStderr();
   const from = SOURCES[source];
   const inputPath = path.join(contentDir, from.file);
   if (!fs.existsSync(inputPath)) {
@@ -75,7 +79,7 @@ export async function runConvert({ source = 'mintlify', contentDir, force = fals
   }
 
   if (dryRun) {
-    log.line(text);
+    process.stdout.write(text);
   } else {
     fs.writeFileSync(outPath, text);
     log.success(`Converted ${from.file} to ${color.bold(displayPath(outPath))}`);

package/src/cli/dev.js

@@ -1,10 +1,11 @@
 import { runAstro } from './run-astro.js';
-import { preflightCheck } from './preflight.js';
+import { preflightCheck, sameDriveCheck, writableInstallCheck } 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';
+import { showUpdateNotice } from './update-check.js';
 
 // 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
@@ -14,6 +15,7 @@ const REPEAT_WINDOW_MS = 2000;
 export async function runDev({ contentDir, packageRoot, port, verbose = false }) {
   const started = Date.now();
   preflightCheck(contentDir);
+  writableInstallCheck(packageRoot);
   const other = runningPreview(packageRoot);
   if (other) {
     log.error(`Another writedocs preview is already running${other.url ? ` at ${other.url}` : ''}.`);
@@ -28,6 +30,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
   process.on('exit', () => removeLock(packageRoot));
 
   const api = await generateApiPages({ contentDir });
+  sameDriveCheck(contentDir, packageRoot, { generatedPages: api.groups.length > 0 });
   reportApiPages(api);
   api.warnings.forEach((message) => log.warn(message));
 
@@ -96,6 +99,9 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
           log.line();
           log.line(color.dim('  Edit any page and the preview updates. Press Ctrl+C to stop.'));
           log.line();
+          // `dev` runs until Ctrl+C - the notice goes under the ready screen,
+          // not after the command like everywhere else.
+          showUpdateNotice();
           return;
         }
         case 'fatal':

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

@@ -5,6 +5,7 @@ import matter from 'gray-matter';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { parseOpenApiRef, openApiOperationKey, specDirName } from '../lib/openapi-ref.js';
 import { findAllPages } from '../lib/pages.js';
+import { readConfigText } from '../lib/config-file.js';
 import { HTTP_METHODS, collectOpenApiGroups } from '../lib/openapi-spec.js';
 
 
@@ -298,13 +299,12 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
  */
 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');
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(writedocsJsonPath, 'utf-8'));
+    config = JSON.parse(readConfigText(contentDir));
   } catch {
     return summary; // preflightCheck() (run first, see dev.js/build.js) already reports this
   }

package/src/cli/init.js

@@ -6,7 +6,9 @@ const WRITEDOCS_JSON = {
   name: 'My Docs',
   description: 'Documentation site built with Writedocs',
   styles: {
-    colors: { primary: '#6366f1' },
+    // Readable as link text on both default backgrounds - a new project
+    // passes `writedocs a11y` (scripts/init.test.js).
+    colors: { primary: '#4f46e5', dark: { primary: '#a5b4fc' } },
   },
   navigation: [
     { group: 'Getting Started', pages: ['index', 'docs/getting-started'] },

package/src/cli/output.js

@@ -9,13 +9,20 @@
 // it finishes. NO_COLOR turns colors off; FORCE_COLOR turns them on.
 import path from 'node:path';
 
-const stream = process.stdout;
+let 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;
 });
+
+/** Sends everything this module prints to stderr from here on - for a
+ *  command whose stdout is data: `convert --dry-run` prints the converted
+ *  writedocs.json there, so `> writedocs.json` gets exactly that. */
+export function logToStderr() {
+  stream = process.stderr;
+}
 const interactive = Boolean(stream.isTTY) && process.env.TERM !== 'dumb' && !process.env.CI;
 const useColor =
   process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0'

package/src/cli/preflight.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { log, color, CliExit } from './output.js';
+import { readConfigText } from '../lib/config-file.js';
 
 /**
  * Fast, dependency-light sanity check that runs before handing off to
@@ -28,7 +30,7 @@ export function preflightCheck(contentDir) {
     throw new CliExit(1);
   }
   try {
-    JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    JSON.parse(readConfigText(contentDir));
   } catch (err) {
     log.error(`writedocs.json is not valid JSON: ${err.message}`);
     log.detail(color.dim('Run "writedocs validate" to see where.'));
@@ -41,3 +43,63 @@ export function preflightCheck(contentDir) {
   // later, with a more specific error naming the missing page - see
   // getStaticPaths() in src/pages/[...slug].astro.
 }
+
+/** The drive (`C:`) or UNC share a Windows path lives on, lowercased. */
+function volumeOf(p) {
+  return path.win32.parse(path.win32.resolve(p)).root.replace(/[\\/]+$/, '').toLowerCase();
+}
+
+/**
+ * Windows only, before `dev`/`build` start Astro: the project has to be on
+ * the same drive as writedocs itself. Astro is run with writedocs' own
+ * folder as its root (see run-astro.js) and records every page's path
+ * relative to it - across drives there is no relative path, the
+ * `D:/...` it gets instead reads as a URL scheme, and the build dies with
+ * "The URL must be of scheme file". The same holds for the temp folder
+ * when it holds generated OpenAPI pages (`generatedPages` - writedocsTempDir()
+ * is Astro content then; the cache and inline React components there build
+ * fine across drives). This stops with what to do instead of that message.
+ * `platform` and `tempDir` are parameters for tests.
+ */
+export function sameDriveCheck(contentDir, packageRoot, { generatedPages = false, platform = process.platform, tempDir = os.tmpdir() } = {}) {
+  if (platform !== 'win32') return;
+  const install = volumeOf(packageRoot);
+  const project = volumeOf(contentDir);
+  if (project !== install) {
+    log.error(`This project is on ${project.toUpperCase()}, and writedocs is installed on ${install.toUpperCase()} - Astro can't build across drives on Windows.`);
+    log.detail(color.dim('Install writedocs in the project instead (npm install --save-dev @writedocs/generator, then npx writedocs ...),'));
+    log.detail(color.dim(`or move the project to drive ${install.toUpperCase()}.`));
+    throw new CliExit(1);
+  }
+  const temp = volumeOf(tempDir);
+  if (generatedPages && temp !== install) {
+    log.error(`The temp folder (${tempDir}) is on ${temp.toUpperCase()}, and writedocs is installed on ${install.toUpperCase()} - Astro can't build the generated API pages across drives on Windows.`);
+    log.detail(color.dim(`Point TEMP and TMP at a folder on drive ${install.toUpperCase()}, or install writedocs on ${temp.toUpperCase()}.`));
+    throw new CliExit(1);
+  }
+}
+
+/**
+ * Before `dev`/`build` start Astro: writedocs has to be able to write inside
+ * its own folder - Astro runs with it as its root (run-astro.js), and keeps
+ * `.astro/`, Vite's `node_modules/.vite/` and the build's staging folder
+ * (writedocsBuildStagingDir()) there. A global install made with sudo is
+ * owned by root, and both commands then die on a bare EACCES/EPERM from
+ * deep inside Astro or Vite. A real write, not fs.accessSync(): on Windows
+ * that only looks at the read-only attribute, not at permissions.
+ */
+export function writableInstallCheck(packageRoot) {
+  const probe = path.join(packageRoot, '.astro', `.write-check-${process.pid}`);
+  try {
+    fs.mkdirSync(path.dirname(probe), { recursive: true });
+    fs.writeFileSync(probe, '');
+    fs.rmSync(probe, { force: true });
+  } catch (err) {
+    if (err.code !== 'EACCES' && err.code !== 'EPERM') throw err;
+    log.error(`writedocs can't write to its own folder (${packageRoot}), and dev and build need to.`);
+    log.detail(color.dim('This happens with a global install made with sudo. Install writedocs in the project instead'));
+    log.detail(color.dim('(npm install --save-dev @writedocs/generator, then npx writedocs ...), or set npm up to install'));
+    log.detail(color.dim('globally without sudo: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally'));
+    throw new CliExit(1);
+  }
+}

package/src/cli/update-check-refresh.js

@@ -0,0 +1,18 @@
+// Detached background process started by update-check.js: asks the npm
+// registry for the latest version of package `process.argv[2]` and caches
+// the answer for the next writedocs run. Prints nothing. A failure (offline,
+// registry down) keeps the last known version but still records the
+// attempt, so it's retried the next day, not on every command.
+import { fetchLatestVersion, readCache, writeCache } from './update-check.js';
+
+const name = process.argv[2];
+let latest = null;
+try {
+  latest = await fetchLatestVersion(name);
+} catch {
+  const previous = readCache();
+  latest = previous?.name === name ? previous.latest : null;
+}
+try {
+  writeCache({ name, latest, checkedAt: Date.now() });
+} catch {}

package/src/cli/update-check.js

@@ -0,0 +1,104 @@
+// "A newer writedocs is available" - shown after any command's output.
+//
+// Never slows a command down: the notice comes from a cached answer, and
+// when that's more than a day old, a detached background process
+// (update-check-refresh.js) asks the npm registry again and rewrites the
+// cache for the next run - the same approach as npm's own update notifier.
+//
+// Not shown for `build` (the WriteDocs platform runs it, not a person) or
+// `update` itself, in CI, when output isn't a terminal, when writedocs runs
+// from a source checkout (updated with git, not npm), or with
+// WRITEDOCS_NO_UPDATE_CHECK set.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { log, color } from './output.js';
+
+const DAY = 24 * 60 * 60 * 1000;
+const SILENT_COMMANDS = new Set(['build', 'update']);
+
+export function cacheFile() {
+  const base =
+    process.env.XDG_CACHE_HOME ||
+    (process.platform === 'win32' ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local') : path.join(os.homedir(), '.cache'));
+  return path.join(base, 'writedocs', 'update-check.json');
+}
+
+export function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(data) {
+  const file = cacheFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data));
+}
+
+/** The registry the user's npm uses, or npm's own. */
+export function registryUrl() {
+  const configured = process.env.npm_config_registry || process.env.NPM_CONFIG_REGISTRY;
+  return (configured || 'https://registry.npmjs.org').replace(/\/+$/, '');
+}
+
+/** The version npm's `latest` tag points at. Throws on a network error. */
+export async function fetchLatestVersion(name, { timeoutMs = 5000 } = {}) {
+  const res = await fetch(`${registryUrl()}/-/package/${name.replace('/', '%2f')}/dist-tags`, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new Error(`the registry answered ${res.status}`);
+  const tags = await res.json();
+  if (typeof tags?.latest !== 'string') throw new Error('the registry has no "latest" version');
+  return tags.latest;
+}
+
+/** Whether `latest` is a newer release than `current` - x.y.z only; a
+ *  prerelease never counts as newer. */
+export function isNewer(latest, current) {
+  const parse = (v) => /^(\d+)\.(\d+)\.(\d+)$/.exec(String(v).trim())?.slice(1).map(Number);
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+export function isSourceCheckout(packageRoot) {
+  return fs.existsSync(path.join(packageRoot, '.git'));
+}
+
+function enabled(command, packageRoot) {
+  if (SILENT_COMMANDS.has(command)) return false;
+  if (process.env.WRITEDOCS_NO_UPDATE_CHECK || process.env.CI) return false;
+  if (!process.stdout.isTTY) return false;
+  return !isSourceCheckout(packageRoot);
+}
+
+let state = null;
+
+/** Called once at startup: loads the cached answer, and refreshes it in the
+ *  background when it's old. */
+export function startUpdateCheck({ command, name, version, packageRoot }) {
+  if (!enabled(command, packageRoot)) return;
+  const cache = readCache();
+  state = { name, version, latest: cache?.name === name ? cache.latest : null, shown: false };
+  if (cache?.name === name && Date.now() - (cache.checkedAt ?? 0) < DAY) return;
+  try {
+    const worker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'update-check-refresh.js');
+    const child = spawn(process.execPath, [worker, name], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.unref();
+  } catch {
+    // No notice this time - not worth failing a command over.
+  }
+}
+
+/** Prints the notice, if there's a newer version - once per run. */
+export function showUpdateNotice() {
+  if (!state || state.shown || !state.latest || !isNewer(state.latest, state.version)) return;
+  state.shown = true;
+  log.line();
+  log.info(`writedocs ${color.bold(state.latest)} is available ${color.dim(`(you have ${state.version})`)}. Run ${color.cyan('writedocs update')} to update.`);
+}