@writedocs/generator 0.1.0

package/src/lib/styles-asset-integration.js

@@ -0,0 +1,210 @@
+// Lets a static asset referenced by a root-relative URL - a writedocs.json
+// field (styles.favicon, styles.logo, footer.logo, styles.background.
+// images.{light,dark}, seo.ogImage, styles.fonts.*.source - the exact set
+// collectConfiguredAssetPaths() in lib/config.ts resolves) *or* a plain
+// image written directly into a page's own MDX/Markdown body
+// (`![alt](/images/foo.png)`, a raw `<img src="/images/foo.png">`, the
+// `<Image src="...">` component, `<Card img="...">`, ...) - resolve from
+// *anywhere* in the project, not just public/. "Any place to store
+// assets" is the whole point: a site author shouldn't have to know Astro
+// has a public/ convention at all, let alone reorganize their project
+// around it, just to reference an image from a doc page.
+//
+// Deliberately NOT implemented as "copy everything into public/ (or a
+// merged scratch dir) before Astro starts, then leave Astro's own
+// publicDir alone": that would either (a) write into the user's own
+// public/ folder as a side effect - a real file appearing in their
+// project tree that they didn't create, which writedocsTempDir()'s own
+// doc comment already argues against doing anywhere in this codebase, or
+// (b) point publicDir at a one-shot copied scratch dir instead of the
+// real public/, which would regress `writedocs dev`'s live file-reload
+// for the *existing*, common case of a file genuinely living under
+// public/ - Vite's own dev server watches and serves publicDir straight
+// off disk per-request with no copy step involved at all today; a byte
+// copy taken once at startup wouldn't pick up a live edit to that file
+// without a full dev-server restart.
+//
+// Instead, this is a small Astro integration with two hooks, each
+// resolving fresh rather than relying on any one-shot copy:
+// - astro:server:setup (dev): adds Vite dev-server middleware that
+//   intercepts any request whose extension looks like a static asset
+//   (looksLikeAssetPath() below - images/fonts, the same set
+//   MIME_BY_EXTENSION already knows how to serve) and - only if it
+//   doesn't already exist under public/ (that stays Vite's own job,
+//   unshadowed) - streams it straight from wherever it lives in the
+//   project. Not scoped to writedocs.json's own configured fields specifically
+//   (an earlier version of this file was) - a page's own MDX can
+//   reference an image path this integration has no way to know about
+//   ahead of time short of parsing every page's content on every
+//   request, so instead of trying to enumerate what *should* be
+//   reachable, it just resolves whatever *is* actually requested,
+//   directly, the same way Vite's own publicDir serving already does.
+// - astro:build:done: a one-time pass after Astro's own build finishes.
+//   First, the same writedocs.json-field-driven copy as before (still needed
+//   as its own pass - background images/font sources render into CSS
+//   `url(...)` inside a `<style>` block, and seo.ogImage into a `<meta
+//   content="...">` tag, neither of which the second pass below would
+//   ever see). Second, copyReferencedContentAssets() below scans every
+//   built .html page for `src="/..."` references (an `<img>`, mainly -
+//   see its own comment) not already present in the output, and resolves
+//   + copies each the same way - this is what actually covers a plain
+//   content image, since there's no fixed field name to read it from up
+//   front the way there is for writedocs.json's own fields. A real static
+//   build has no "later" for a live-reload concern to apply to, so a
+//   single pass of each here is sufficient.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDocsConfig, collectConfiguredAssetPaths } from './config.ts';
+
+const MIME_BY_EXTENSION = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+function mimeFor(filePath) {
+  return MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+
+/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
+ *  `contentDir` directly - not `<contentDir>/public` - the fallback
+ *  location for one of the styles/footer/seo asset fields
+ *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
+ *  Segment-by-segment path-traversal guard (no
+ *  `..`/`.` segments) since `urlPath` ultimately comes from an incoming
+ *  request URL in the dev-server case, not just trusted writedocs.json
+ *  content. Returns an absolute path, or null if nothing real is there. */
+function resolveOutsidePublic(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
+  const absolute = path.join(contentDir, ...segments);
+  try {
+    return fs.statSync(absolute).isFile() ? absolute : null;
+  } catch {
+    return null;
+  }
+}
+
+function publicPathFor(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  return path.join(contentDir, 'public', ...segments);
+}
+
+/** Root-relative, recognized-extension paths only - the same "does this
+ *  look like a static asset at all" question mimeFor()'s own map already
+ *  answers, reused here as the dev-middleware/build-scan gate instead of
+ *  a fixed list of writedocs.json field names. Deliberately permissive: a page
+ *  or config field asking for a path this returns true for gets a real
+ *  attempt to resolve it from anywhere in the project; anything else
+ *  (an actual API route, a `.html` page request, ...) is left alone,
+ *  same as before this existed. */
+function looksLikeAssetPath(urlPath) {
+  return Object.prototype.hasOwnProperty.call(MIME_BY_EXTENSION, path.extname(urlPath).toLowerCase());
+}
+
+/** Recursively lists every `.html` file under `dir`. Astro's own build
+ *  output is already a flat-ish tree of one .html per route, so this is
+ *  just a plain walk - no globbing dependency needed for something this
+ *  small. */
+function listHtmlFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listHtmlFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.html')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/** Scans every built page for root-relative, recognized-extension `src="/..."`
+ *  references (`<img src="...">`, mainly - what `Image.astro`, `Frame.astro`,
+ *  and a raw `![]()`/`<img>` in MDX all ultimately render down to; a
+ *  `srcset="..."` attribute is checked too, since it's the same kind of
+ *  reference and costs nothing extra to also cover) that aren't already
+ *  present in the build output, and copies each one in from wherever it
+ *  resolves in the project via resolveOutsidePublic() - the same
+ *  fallback the dev middleware below already uses, just applied once,
+ *  after the fact, to the rendered HTML instead of to live requests.
+ *  This is what actually covers a plain content-body image: unlike a
+ *  writedocs.json field, there's no fixed set of field names to read a
+ *  content image's path from ahead of time, so instead this reads
+ *  whatever `src` a page's own rendered markup ends up containing. */
+function copyReferencedContentAssets(outDir, contentDir) {
+  const attrPattern = /\b(?:src|srcset)="([^"]+)"/g;
+  for (const htmlFile of listHtmlFiles(outDir)) {
+    const html = fs.readFileSync(htmlFile, 'utf8');
+    let match;
+    while ((match = attrPattern.exec(html))) {
+      // srcset can hold a comma-separated list of "url descriptor" pairs -
+      // split it out; a plain src is already just the one URL.
+      const candidates = match[1].split(',').map((part) => part.trim().split(/\s+/)[0]).filter(Boolean);
+      for (const urlPath of candidates) {
+        if (!urlPath.startsWith('/') || urlPath.startsWith('//')) continue; // only root-relative - not external, not protocol-relative
+        if (!looksLikeAssetPath(urlPath)) continue;
+        const segments = urlPath.replace(/^\/+/, '').split('/');
+        const outPath = path.join(outDir, ...segments);
+        if (fs.existsSync(outPath)) continue; // already present - via public/'s passthrough copy, or a previous iteration of this same loop
+        const resolved = resolveOutsidePublic(urlPath, contentDir);
+        if (!resolved) continue; // doesn't resolve to a real file anywhere in the project either - leave the broken reference as-is, same as today
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.copyFileSync(resolved, outPath);
+      }
+    }
+  }
+}
+
+export function stylesAssetFallback(contentDir) {
+  return {
+    name: 'writedocs-styles-asset-fallback',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        server.middlewares.use((req, res, next) => {
+          if (!req.url) return next();
+          const urlPath = req.url.split('?')[0];
+          if (!looksLikeAssetPath(urlPath)) return next();
+          if (fs.existsSync(publicPathFor(urlPath, contentDir))) return next(); // real public/ file - Vite's own static serving already handles it, don't shadow
+          const resolved = resolveOutsidePublic(urlPath, contentDir);
+          if (!resolved) return next();
+          res.setHeader('Content-Type', mimeFor(resolved));
+          fs.createReadStream(resolved).pipe(res);
+        });
+      },
+      'astro:build:done': async ({ dir }) => {
+        const outDir = fileURLToPath(dir);
+        const config = loadDocsConfig(contentDir);
+        // Pass 1: writedocs.json's own configured fields. Kept as its own,
+        // field-name-driven pass rather than folded into pass 2 below -
+        // background images/font sources render into CSS `url(...)`
+        // inside a `<style>` block, and seo.ogImage into a `<meta
+        // content="...">` tag, none of which pass 2's src="..."/
+        // srcset="..." attribute scan would ever see.
+        for (const urlPath of collectConfiguredAssetPaths(config)) {
+          const segments = urlPath.replace(/^\/+/, '').split('/');
+          const outPath = path.join(outDir, ...segments);
+          if (fs.existsSync(outPath)) continue; // already present via public/'s normal passthrough copy
+          const resolved = resolveOutsidePublic(urlPath, contentDir);
+          if (!resolved) continue; // not configured to a real file anywhere - same as today, just renders a broken <link>/<img>
+          fs.mkdirSync(path.dirname(outPath), { recursive: true });
+          fs.copyFileSync(resolved, outPath);
+        }
+        // Pass 2: arbitrary content-body assets - anything a page's own
+        // rendered HTML references by src/srcset that pass 1 didn't
+        // already account for.
+        copyReferencedContentAssets(outDir, contentDir);
+      },
+    },
+  };
+}

package/src/lib/writedocs-temp-dir.js

@@ -0,0 +1,93 @@
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/** Where writedocs' own generated/cached artifacts for a given content
+ *  directory live: Astro's content-layer cache (`cacheDir`), the
+ *  auto-generated OpenAPI stub pages the `generatedDocs` collection reads
+ *  (see content.config.ts), and the resolved-operation JSON
+ *  ApiPlayground.astro/ApiReferencePanel.astro read at render time (see
+ *  lib/openapi-render.ts). All three used to live under
+ *  `<contentDir>/.writedocs/` - moved out entirely (into the OS temp
+ *  directory instead) so `writedocs dev`/`build` never writes anything
+ *  into a person's own project folder for them to notice, gitignore, or
+ *  accidentally commit.
+ *
+ *  Namespaced by a short hash of contentDir's own resolved absolute path,
+ *  not a fixed name, for two reasons: different content directories
+ *  (this repo's own docs.json-examples/* fixtures, or two unrelated
+ *  projects on the same machine using the same globally-installed
+ *  writedocs) must never collide with each other on disk - see the
+ *  "Content-layer cache collision" bug note in
+ *  docs/dev/docs/architecture.mdx for what happens when they do - while
+ *  repeated runs *of the same project* should keep reusing the same
+ *  directory (Astro's content-layer cache is only useful if it survives
+ *  across dev/build runs). The human-readable prefix is only there to
+ *  make a real temp directory recognizable while debugging; nothing
+ *  parses it back out.
+ *
+ *  Deliberately a plain .js module, not .ts: src/cli/generate-api-pages.js
+ *  runs via plain Node before Astro/Vite's TS-aware pipeline exists (see
+ *  that file's own comment on why it otherwise avoids importing from
+ *  lib/config.ts), so this is the one shared path-computation helper it
+ *  can still import directly. Every other call site (astro.config.mjs,
+ *  content.config.ts, src/pages/[...slug].astro, src/pages/[...slug].md.ts,
+ *  lib/config.ts, lib/openapi-render.ts) imports this exact same file too
+ *  - all of them need to agree on the identical path, since one writes
+ *  what another reads. */
+function namespaceLabel(contentDir) {
+  const resolved = path.resolve(contentDir);
+  const hash = crypto.createHash('sha1').update(resolved).digest('hex').slice(0, 12);
+  const label = path.basename(resolved) || 'root';
+  return `${label}-${hash}`;
+}
+
+export function writedocsTempDir(contentDir) {
+  return path.join(os.tmpdir(), 'writedocs', namespaceLabel(contentDir));
+}
+
+/** Where `astro build` actually writes its output during the build itself
+ *  - deliberately *inside* the installed writedocs package (packageRoot),
+ *  never contentDir/dist directly, and never OS temp either (unlike
+ *  writedocsTempDir() above). build.js copies the finished result from
+ *  here into the real `<contentDir>/dist` as an explicit final step once
+ *  Astro's own build has fully finished - see that file's own comment for
+ *  why a plain recursive copy, not Astro's default in-place output.
+ *
+ *  The short version: Astro's static build stages its prerendered output
+ *  in `<outDir>/.prerender/` and then does a plain `fs.rename()` into the
+ *  real outDir (astro/dist/prerender/utils.js) - which throws `EXDEV:
+ *  cross-device link not permitted` the moment outDir and that staging
+ *  location land on different filesystems. Astro decides *where* to stage
+ *  by checking whether outDir starts with `process.cwd()`
+ *  (getOutDirWithinCwd) - pointing outDir at contentDir/dist directly (the
+ *  obvious-looking fix) makes that check pass, but doesn't just move
+ *  *where* staging happens, it moves *where Astro's own SSR/prerender
+ *  bundle physically executes from* - and that bundle isn't fully
+ *  self-contained: some of Astro's own dependencies (Tailwind's Vite
+ *  plugin registering a loader hook that reaches for a small terminal-
+ *  color-formatting package, observed directly while diagnosing this) do
+ *  a bare-specifier `import` Node has to resolve the normal way - walking
+ *  up from wherever that code physically executes looking for a
+ *  `node_modules` containing it. contentDir has no `node_modules` at all
+ *  by design (see docs/dev/docs/architecture.mdx) - a real consumer's
+ *  project is just `writedocs.json` + a content folder - so once the SSR
+ *  bundle executes from inside contentDir, *that* resolution fails
+ *  instead, trading one crash for a less predictable one that depends on
+ *  which of Astro's own runtime code paths a given site's content happens
+ *  to trigger.
+ *
+ *  Staying inside packageRoot keeps every one of those bare specifiers
+ *  resolving exactly the way it already does today (this is where
+ *  `node_modules` actually lives), while a plain `fs.cp()` - which copies
+ *  across filesystem boundaries just fine, unlike `rename()` - handles the
+ *  one genuinely cross-device step explicitly, once, after Astro is
+ *  completely done needing any of its own dependencies to still resolve.
+ *
+ *  Namespaced by the same contentDir-hash convention as writedocsTempDir()
+ *  above, so two different content directories building against the same
+ *  globally-installed writedocs (or two concurrent builds) never collide
+ *  here either. */
+export function writedocsBuildStagingDir(packageRoot, contentDir) {
+  return path.join(packageRoot, '.writedocs-build', namespaceLabel(contentDir));
+}

package/src/pages/404.astro

@@ -0,0 +1,62 @@
+---
+// Astro's own file-based convention: a static build (`output: 'static'`,
+// this package's only supported mode - see astro.config.mjs) emits this
+// file's output as a literal `404.html` at the site root, and most static
+// hosts (Netlify, Vercel, GitHub Pages, Cloudflare Pages, ...) serve it
+// automatically for any unmatched path. No params, no getStaticPaths -
+// this is a single fixed route, same category as llms.txt.ts/
+// llms-full.txt.ts (see their own comments on Astro auto-prerendering a
+// non-dynamic page at its literal path).
+import { loadDocsConfig } from '../lib/config';
+import BaseLayout from '../layout/BaseLayout.astro';
+
+const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+const config = loadDocsConfig(contentDir);
+
+// writedocs.json's `notFound.{title,description}` (notFoundSchema in
+// lib/config.ts) - both optional, with the hardcoded fallbacks below, so
+// a site gets a reasonably branded 404 page without having to configure
+// anything.
+const title = config.notFound.title ?? 'Page not found';
+const description = config.notFound.description ?? "The page you're looking for doesn't exist or has moved.";
+---
+<BaseLayout config={config} title={title} description={description} path="/404/" seo={{ noindex: true }} mode="frame">
+  <div class="wd-404">
+    <p class="wd-404-eyebrow">404</p>
+    <h1>{title}</h1>
+    <p class="wd-404-description">{description}</p>
+    <a class="wd-404-home" href="/">&larr; Back to home</a>
+  </div>
+</BaseLayout>
+
+<style>
+  .wd-404 {
+    max-width: 560px;
+    margin: 0 auto;
+    padding: 5rem 1.5rem 6rem;
+    text-align: center;
+  }
+  .wd-404-eyebrow {
+    margin: 0 0 0.5rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    color: var(--wd-primary);
+  }
+  .wd-404 h1 {
+    margin: 0 0 0.75rem;
+    font-size: 1.75rem;
+  }
+  .wd-404-description {
+    margin: 0 0 2rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-404-home {
+    color: var(--wd-primary);
+    text-decoration: none;
+    font-weight: 500;
+  }
+  .wd-404-home:hover {
+    text-decoration: underline;
+  }
+</style>