@writedocs/generator 0.1.0

package/src/cli/build-auth.js

@@ -0,0 +1,53 @@
+/**
+ * `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.
+ *
+ * This deliberately isn't a local check. An earlier version compared the
+ * supplied key against an env var set on the same machine
+ * (WRITEDOCS_BUILD_SECRET) - but since writedocs ships its full source to
+ * everyone who installs it, anyone could read that check and satisfy it
+ * with a value they made up themselves. Calling out to a server that
+ * 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.
+ */
+export async function requireBuildKey(providedKey) {
+  const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
+  if (!serverUrl) {
+    console.error('[writedocs] build is not available.');
+    process.exit(1);
+  }
+  if (!providedKey) {
+    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY).');
+    process.exit(1);
+  }
+
+  let valid = false;
+  try {
+    const res = await fetch(new URL('/v1/validate', serverUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key: providedKey }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.ok) {
+      const body = await res.json();
+      valid = body?.valid === true;
+    }
+  } catch (err) {
+    // 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}`);
+    process.exit(1);
+  }
+
+  if (!valid) {
+    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY) - the server rejected this one.');
+    process.exit(1);
+  }
+}

package/src/cli/build.js

@@ -0,0 +1,40 @@
+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 { generateApiPages } from './generate-api-pages.js';
+import { writeRedirectsFile } from './write-redirects-file.js';
+import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
+
+export async function runBuild({ contentDir, packageRoot }) {
+  preflightCheck(contentDir);
+  await generateApiPages({ contentDir });
+  console.log(`[writedocs] Building ${contentDir} -> ${contentDir}/dist`);
+  await runAstro(['build', '--root', packageRoot], { packageRoot, contentDir });
+  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
+  // function's own comment (writedocs-temp-dir.js) for why. fs.cpSync
+  // (unlike the fs.rename() Astro uses internally to get *into* that
+  // staging dir in the first place) copies across filesystem boundaries
+  // without issue, so this is the one step that actually needs to bridge
+  // packageRoot and contentDir potentially living on different devices.
+  // distDir is cleared first so a rebuild doesn't leave a stale file
+  // behind from a previous build that the new one no longer produces -
+  // the same "the output directory reflects exactly this build, nothing
+  // older" expectation `astro build` itself already guarantees when
+  // writing directly into outDir.
+  const stagingDir = writedocsBuildStagingDir(packageRoot, contentDir);
+  fs.rmSync(distDir, { recursive: true, force: true });
+  fs.cpSync(stagingDir, distDir, { recursive: true });
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+  // Astro's own writedocs.json `redirects` + the automatic "/" redirect only
+  // ever produce client-side meta-refresh pages (see write-redirects-file.js)
+  // - 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`);
+}

package/src/cli/dev.js

@@ -0,0 +1,12 @@
+import { runAstro } from './run-astro.js';
+import { preflightCheck } from './preflight.js';
+import { generateApiPages } from './generate-api-pages.js';
+
+export async function runDev({ contentDir, packageRoot, port }) {
+  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 });
+}

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

@@ -0,0 +1,359 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import SwaggerParser from '@apidevtools/swagger-parser';
+import matter from 'gray-matter';
+import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+/** Canonical "METHOD /path" key used everywhere an operation needs to be
+ *  identified: the manifest, a hand-written page's `openapi:` frontmatter,
+ *  and the ApiPlayground component's own `operation` prop all use exactly
+ *  this format, so no separate id scheme needs to be invented or kept in
+ *  sync. */
+function operationKey(method, urlPath) {
+  return `${method.toUpperCase()} ${urlPath}`;
+}
+
+/** Filesystem-safe form of an operation key, for the per-operation JSON
+ *  file written under writedocsTempDir()/openapi/<path>/operations/ - the
+ *  sanitization only needs to be *stable and collision-free*, not
+ *  reversible (the operation's own method/path are stored inside the
+ *  JSON body too). */
+function operationFileName(method, urlPath) {
+  return `${method.toLowerCase()}_${urlPath.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')}.json`;
+}
+
+function slugify(value) {
+  return (
+    value
+      .toLowerCase()
+      .replace(/[{}]/g, '')
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'root'
+  );
+}
+
+/** Strips leading/trailing slashes from a group's `openapi.path`, giving
+ *  the value used both as the URL prefix segment and as this spec's own
+ *  namespace directory under writedocsTempDir()/openapi/ - e.g. "/api" -> "api",
+ *  "/v2/api/" -> "v2/api" (multi-segment paths just nest normally, both
+ *  as generated docs/ subdirectories and as a manifest directory path). */
+function normalizePathPrefix(rawPath) {
+  return rawPath.replace(/^\/+|\/+$/g, '');
+}
+
+/** The generated stub's own file id (writedocs.json-navigation-facing path,
+ *  and the actual URL it's served at) for an operation with no
+ *  hand-written override - namespaced under the owning group's own
+ *  `path` prefix (so two openapi groups never collide with each other),
+ *  then grouped by its first tag (or "untagged") purely for directory
+ *  tidiness, mirroring how a hand-authored API reference is usually
+ *  organized. Also doubles as the stub's own on-disk path relative to
+ *  writedocsTempDir()'s generated-docs/ directory (see
+ *  generateApiPagesForGroup below) -
+ *  there's no docs/ tree to avoid colliding with any more (unlike a
+ *  hand-written page, which could live anywhere), so this can be the
+ *  literal file path too, with no separate "_generated/" prefix needed
+ *  to keep it out of a hand-written page's own namespace. */
+function generatedSlugFor(pathPrefix, method, urlPath, tags) {
+  const tagSlug = slugify(tags[0] ?? 'untagged');
+  const opSlug = slugify(`${method}-${urlPath}`);
+  return `${pathPrefix}/${tagSlug}/${opSlug}`;
+}
+
+/** Directories at the content root a hand-written-override scan never
+ *  descends into - mirrors EXCLUDED_TOP_LEVEL_DIRS in lib/config.ts's
+ *  findAllPages() exactly (this file deliberately doesn't import that TS
+ *  module - see collectOpenApiGroups()'s own doc comment on the same
+ *  point - so the same small list is just duplicated here). docs/ has no
+ *  special status - scanned like any other folder, same as page
+ *  discovery itself. */
+const OVERRIDE_SCAN_EXCLUDED_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
+
+/** Recursively scans `contentDir` for .md/.mdx files claiming an
+ *  operation via frontmatter `openapi: "METHOD /path"`, recording each
+ *  one's file id - its path relative to `contentDir`, extension
+ *  stripped, trailing `/index` segment dropped (mirroring Astro's own
+ *  default id computation exactly - see fileIdForEntry()'s comment in
+ *  lib/config.ts for why that stripping matters: without it, an override
+ *  page at e.g. `docs/webhooks/index.mdx` would be recorded under a file
+ *  id ("docs/webhooks/index") the rest of the routing pipeline would
+ *  never actually resolve, since the page's real id is "docs/webhooks") -
+ *  into `overrides`, skipping OVERRIDE_SCAN_EXCLUDED_DIRS at the content
+ *  root's own top level. */
+function scanDirForOverrides(dir, relBase, overrides) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (relBase === '' && OVERRIDE_SCAN_EXCLUDED_DIRS.has(entry.name)) continue;
+      scanDirForOverrides(full, rel, overrides);
+      continue;
+    }
+    if (!/\.mdx?$/i.test(entry.name)) continue;
+    const raw = fs.readFileSync(full, 'utf-8');
+    const { data } = matter(raw);
+    if (typeof data.openapi !== 'string') continue;
+    const fileId = rel.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+    overrides.set(data.openapi.trim().replace(/\s+/g, ' '), fileId);
+  }
+}
+
+/** Scans for hand-written pages that claim an operation via frontmatter
+ *  `openapi: "METHOD /path"` - these always win over an auto-generated
+ *  stub for the same operation, so an author can add custom prose above
+ *  the playground for any specific endpoint without losing the
+ *  auto-generated coverage for everything else. Scanned once and shared
+ *  across every openapi group in writedocs.json (not scoped to a single spec)
+ *  - simplest to reason about, and in practice a method+path colliding
+ *  across two genuinely different specs mounted in the same site is rare
+ *  enough not to be worth a more elaborate per-spec disambiguation scheme
+ *  unless it turns out to matter. A single scan of the whole content
+ *  directory (docs/ has no special status - see scanDirForOverrides()
+ *  above), so a hand-authored override page works the same wherever it
+ *  lives. */
+function findHandWrittenOverrides(contentDir) {
+  const overrides = new Map(); // operationKey -> file id
+  scanDirForOverrides(contentDir, '', overrides);
+  return overrides;
+}
+
+function resolveSecurity(operation, spec) {
+  const requirements = operation.security ?? spec.security ?? [];
+  const schemes = spec.components?.securitySchemes ?? {};
+  return requirements
+    .flatMap((req) => Object.keys(req))
+    .map((name) => ({ name, ...schemes[name] }))
+    .filter((s) => s.type);
+}
+
+function buildOperations(spec) {
+  const operations = [];
+  for (const [urlPath, pathItem] of Object.entries(spec.paths ?? {})) {
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])];
+      operations.push({
+        method: method.toUpperCase(),
+        path: urlPath,
+        operationId: operation.operationId ?? null,
+        summary: operation.summary ?? null,
+        description: operation.description ?? null,
+        tags: operation.tags ?? [],
+        parameters,
+        requestBody: operation.requestBody ?? null,
+        responses: operation.responses ?? {},
+        servers: operation.servers ?? spec.servers ?? [],
+        security: resolveSecurity(operation, spec),
+      });
+    }
+  }
+  return operations;
+}
+
+function rmrf(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/** Walks writedocs.json's raw `navigation` tree (any shape - a bare array, or
+ *  an object choosing tabs/versions/languages/dropdowns/products, plus
+ *  `global.dropdowns`) looking for group nodes shaped like
+ *  `{ group, openapi: { src, path } }`, however deeply nested inside
+ *  hand-authored groups or containers. Runs directly against the raw
+ *  JSON (before writedocs.json's own zod validation even happens - this CLI
+ *  step runs first, see generateApiPages() below), so it deliberately
+ *  doesn't import anything from lib/config.ts and just duck-types each
+ *  node the same way lib/config.ts's own walkSections()/
+ *  expandOpenApiInContainer() do. */
+function collectOpenApiGroups(navigation) {
+  const found = [];
+
+  function fromPagesItem(item) {
+    if (!item || typeof item !== 'object') return; // plain page-slug string - not a group
+    if (item.group && item.openapi) {
+      found.push(item);
+      return;
+    }
+    if (Array.isArray(item.pages)) {
+      for (const child of item.pages) fromPagesItem(child);
+    }
+    // otherwise a { label, href } link leaf - nothing to collect
+  }
+
+  function fromContainer(node) {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node.pages)) {
+      for (const item of node.pages) fromPagesItem(item);
+    } else if (Array.isArray(node.tabs)) {
+      for (const t of node.tabs) fromContainer(t);
+    } else if (Array.isArray(node.versions)) {
+      for (const v of node.versions) fromContainer(v);
+    } else if (Array.isArray(node.languages)) {
+      for (const l of node.languages) fromContainer(l);
+    } else if (Array.isArray(node.dropdowns)) {
+      for (const d of node.dropdowns) fromContainer(d);
+    } else if (Array.isArray(node.products)) {
+      for (const p of node.products) fromContainer(p);
+    }
+    // otherwise a bare { href } container - nothing to collect
+  }
+
+  if (Array.isArray(navigation)) {
+    for (const item of navigation) fromPagesItem(item);
+  } else if (navigation && typeof navigation === 'object') {
+    if (Array.isArray(navigation.global?.dropdowns)) {
+      for (const d of navigation.global.dropdowns) fromContainer(d);
+    }
+    fromContainer(navigation);
+  }
+
+  return found;
+}
+
+/** Generates every page for one `{ group, openapi: { src, path } }`
+ *  navigation node: dereferences its spec, writes a stub page per
+ *  operation (unless a hand-written override already claims it), and
+ *  writes this spec's own manifest + resolved operation JSON under
+ *  writedocsTempDir()'s openapi/<path>/ directory - namespaced by `path` so multiple specs
+ *  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 }) {
+  const pathPrefix = normalizePathPrefix(group.openapi.path);
+  const specPath = path.resolve(contentDir, group.openapi.src);
+  if (!fs.existsSync(specPath)) {
+    throw new Error(
+      `[writedocs] writedocs.json's "${group.group}" group has openapi.src "${group.openapi.src}" ` +
+        `(resolved to ${specPath}), which doesn't exist`
+    );
+  }
+
+  console.log(`[writedocs] Parsing OpenAPI spec for "${group.group}": ${group.openapi.src}`);
+  const spec = await SwaggerParser.dereference(specPath);
+  const operations = buildOperations(spec);
+
+  const openapiOutDir = path.join(writedocsTempDir(contentDir), 'openapi', pathPrefix);
+  fs.mkdirSync(path.join(openapiOutDir, 'operations'), { recursive: true });
+
+  const manifest = [];
+  for (const operation of operations) {
+    const key = operationKey(operation.method, operation.path);
+    const overrideSlug = overrides.get(key);
+    const generated = !overrideSlug;
+    const slug = overrideSlug ?? generatedSlugFor(pathPrefix, operation.method, operation.path, operation.tags);
+    const title = operation.summary ?? `${operation.method} ${operation.path}`;
+
+    if (generated) {
+      // Written under writedocsTempDir()'s generated-docs/ directory
+      // (its own content collection - see content.config.ts) rather than
+      // anywhere inside the project itself, so a site's own project
+      // folder never shows these machine-generated files when a reader
+      // browses it directly. `slug` here doubles as
+      // this file's own path (relative to that collection's base) and
+      // its frontmatter override, so the page's served URL is pinned to
+      // exactly this value regardless of whatever id Astro's own
+      // default (path-derived) computation would otherwise have picked.
+      const filePath = path.join(generatedDocsDir, `${slug}.mdx`);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      const frontmatter = [
+        '---',
+        `title: ${JSON.stringify(title)}`,
+        operation.description ? `description: ${JSON.stringify(operation.description)}` : null,
+        `openapi: ${JSON.stringify(key)}`,
+        `slug: ${JSON.stringify(slug)}`,
+        '---',
+        '',
+      ]
+        .filter((line) => line !== null)
+        .join('\n');
+      fs.writeFileSync(filePath, frontmatter);
+    }
+
+    manifest.push({ slug, method: operation.method, path: operation.path, tags: operation.tags, title, generated });
+
+    const opFile = path.join(openapiOutDir, 'operations', operationFileName(operation.method, operation.path));
+    fs.writeFileSync(opFile, JSON.stringify(operation, null, 2));
+  }
+
+  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}"`);
+}
+
+/**
+ * Runs before Astro starts (both `writedocs dev` and `writedocs build`):
+ * finds every `{ group, openapi: { src, path } }` node anywhere in
+ * writedocs.json's `navigation` tree, and for each one, parses its spec and
+ * either points each operation at an existing hand-written page
+ * (frontmatter `openapi: "METHOD /path"`) or writes a minimal generated
+ * stub under writedocsTempDir()'s generated-docs/ directory - its own
+ * content collection (see content.config.ts), kept entirely out of the
+ * project itself so a site's own project folder never shows these
+ * machine-generated files. (An earlier version of this tried
+ * docs/_generated/ - and, before that, a docs/.generated/ dot-directory,
+ * which Astro's glob loader silently skips outright since fast-glob-style
+ * dotfile exclusion can't be turned off through its public options -
+ * before settling on a fully separate collection instead, which
+ * sidesteps both problems.) Also writes an openapi/<path>/manifest.json
+ * (consumed by lib/config.ts to expand a group's `openapi` shorthand into
+ * concrete `{ group, pages }`) and one resolved operation JSON per
+ * operation under openapi/<path>/operations/ (consumed by
+ * ApiPlayground.astro/ApiReferencePanel.astro at render time - keeping
+ * the actual $ref dereferencing work in this one place rather than
+ * repeating it, or re-adding swagger-parser as an Astro/Vite-side
+ * dependency, per page render), both also under writedocsTempDir(). Each
+ * spec's own output is namespaced under its group's `path`, so any number
+ * of openapi groups can coexist in one writedocs.json without colliding with
+ * each other.
+ *
+ * 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.
+ */
+export async function generateApiPages({ contentDir }) {
+  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'));
+  } catch {
+    return; // preflightCheck() (run first, see dev.js/build.js) already reports this
+  }
+
+  // Always start from a clean slate: a group's `path` (or the group
+  // itself) may have changed or been removed since the last run, and
+  // there's no cheap way to tell stale generated output apart from
+  // still-current output without just regenerating everything.
+  rmrf(generatedDocsDir);
+  rmrf(openapiOutDir);
+
+  const groups = collectOpenApiGroups(config.navigation);
+  if (groups.length === 0) return;
+
+  const seenPaths = new Map(); // normalized path -> owning group's label
+  for (const group of groups) {
+    const normalized = normalizePathPrefix(group.openapi.path);
+    const owner = seenPaths.get(normalized);
+    if (owner) {
+      throw new Error(
+        `[writedocs] writedocs.json has two openapi groups both mounted at "${group.openapi.path}" ` +
+          `("${owner}" and "${group.group}") - give each group's openapi.path a distinct value.`
+      );
+    }
+    seenPaths.set(normalized, group.group);
+  }
+
+  const overrides = findHandWrittenOverrides(contentDir);
+  for (const group of groups) {
+    await generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides });
+  }
+}

package/src/cli/init.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WRITEDOCS_JSON = {
+  name: 'My Docs',
+  description: 'Documentation site built with Writedocs',
+  styles: {
+    colors: { primary: '#6366f1' },
+  },
+  navigation: [
+    { group: 'Getting Started', pages: ['index', 'docs/getting-started'] },
+  ],
+  topbar: { links: [] },
+};
+
+// Lives at the project root, next to writedocs.json itself - not inside docs/
+// - so it keeps file id "index" and serves at "/" with no frontmatter
+// `slug` override needed. See "How a project is structured" in the
+// public docs (site/docs/index.mdx) for why: a nested index.mdx (one
+// inside any folder, docs/ included) has its trailing `/index` segment
+// stripped by Astro's own default id computation, landing it at that
+// folder's own path instead of "/".
+const INDEX_MDX = `---
+title: Introduction
+description: Welcome to your new docs site
+---
+
+Welcome to your new documentation site, built with Writedocs.
+
+<Callout type="tip">
+  Edit \`index.mdx\` to get started, and add pages to \`writedocs.json\`'s
+  navigation to make them appear in the sidebar.
+</Callout>
+`;
+
+const GETTING_STARTED_MDX = `---
+title: Getting Started
+---
+
+<Steps>
+  <Step title="Edit content">
+    A page is any \`.md\`/\`.mdx\` file with a frontmatter block -
+    \`docs/\` is a convenient place to put most of them, but not a
+    requirement.
+  </Step>
+  <Step title="Update navigation">
+    Add the page's path (without extension) to \`writedocs.json\` - a page
+    under \`docs/\` is referenced with that prefix, e.g. \`docs/guides/x\`
+    for \`docs/guides/x.mdx\`.
+  </Step>
+  <Step title="Preview">
+    Run \`writedocs dev\` and open the printed local URL.
+  </Step>
+</Steps>
+`;
+
+export async function runInit({ targetDir }) {
+  fs.mkdirSync(path.join(targetDir, 'docs'), { recursive: true });
+
+  const configPath = path.join(targetDir, 'writedocs.json');
+  if (fs.existsSync(configPath)) {
+    console.error(`[writedocs] writedocs.json already exists in ${targetDir}, skipping.`);
+  } else {
+    fs.writeFileSync(configPath, JSON.stringify(WRITEDOCS_JSON, null, 2) + '\n');
+    console.log(`[writedocs] 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`);
+  }
+
+  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`);
+  }
+
+  console.log(`\n[writedocs] Ready. Run "writedocs dev" to preview your site.`);
+}

package/src/cli/preflight.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Fast, dependency-light sanity check that runs before handing off to
+ * Astro, so users get an immediate, clear error instead of a Vite stack
+ * trace when writedocs.json is missing or malformed JSON.
+ */
+export function preflightCheck(contentDir) {
+  const configPath = path.join(contentDir, 'writedocs.json');
+  if (!fs.existsSync(configPath)) {
+    // The config file used to be named docs.json (renamed to writedocs.json
+    // for a clearer, collision-free name - "docs.json" reads like it could
+    // be *any* project's own docs config, not specifically writedocs'). A
+    // project that still has the old filename around gets a specific
+    // rename hint instead of the generic "none found" message below, since
+    // 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);
+    }
+    console.error(`[writedocs] No writedocs.json found in ${contentDir}`);
+    console.error(`[writedocs] Run "writedocs init" to create one.`);
+    process.exit(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);
+  }
+  // No docs/-folder check here: docs/ isn't a required directory - a page
+  // can live anywhere in the project (see findAllPages() in
+  // src/lib/config.ts). A writedocs.json whose navigation references a
+  // page that genuinely doesn't exist anywhere still fails loudly, just
+  // later, with a more specific error naming the missing page - see
+  // getStaticPaths() in src/pages/[...slug].astro.
+}

package/src/cli/run-astro.js

@@ -0,0 +1,57 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+/**
+ * Resolves the astro CLI entrypoint relative to this package (not the
+ * consumer's project), so it works regardless of how writedocs was
+ * installed (flat or nested node_modules).
+ */
+function resolveAstroBin(packageRoot) {
+  const require = createRequire(path.join(packageRoot, 'package.json'));
+  const astroPkgPath = require.resolve('astro/package.json');
+  const astroPkg = require(astroPkgPath);
+  return path.join(path.dirname(astroPkgPath), astroPkg.bin.astro);
+}
+
+export function runAstro(args, { packageRoot, contentDir }) {
+  const astroBin = resolveAstroBin(packageRoot);
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [astroBin, ...args], {
+      stdio: 'inherit',
+      // Explicit, not inherited: astro.config.mjs's own `outDir` lives
+      // inside packageRoot (writedocsBuildStagingDir() - see its own
+      // comment in writedocs-temp-dir.js for the full EXDEV story this is
+      // one half of), and Astro's static builder only stages its
+      // prerendered output *inside* that outDir - rather than falling
+      // back to `<process.cwd()>/.astro/.prerender/` - when outDir starts
+      // with process.cwd() (getOutDirWithinCwd, astro/dist/core/build/
+      // common.js). Left unset, this child would just inherit whatever
+      // directory the *parent* writedocs CLI process happened to be
+      // launched from - unrelated to packageRoot for a real globally-
+      // installed CLI invoked from wherever the user's shell happens to
+      // be - so the fallback branch would fire regardless, staging
+      // outside packageRoot again and reintroducing the exact module-
+      // resolution problem this whole design is meant to avoid. Pinning
+      // cwd to packageRoot here guarantees the "starts with cwd" check
+      // passes deterministically, independent of the parent process's own
+      // cwd.
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        WRITEDOCS_CONTENT_DIR: contentDir,
+        // Astro is always invoked with `--root packageRoot` (see build.js/
+        // dev.js), so every CollectionEntry's `filePath` comes back
+        // relative to *this*, not to contentDir or the process's cwd.
+        // Exposed so lib/config.ts's fileIdForEntry() can resolve it back
+        // into a docs/-relative file id - see that function for why.
+        WRITEDOCS_PACKAGE_ROOT: packageRoot,
+      },
+    });
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`astro ${args[0]} exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}