svelte-docsmith 0.10.0 → 0.11.0

package/bin/svelte-docsmith.mjs

@@ -1,161 +1,16 @@
 #!/usr/bin/env node
-// The svelte-docsmith maintenance CLI. Currently one command: `archive-version`,
-// which freezes today's docs into an archived version folder so they stay live
-// after a breaking release.
-//
-// The current version is served unprefixed from the docs root and is the folder
-// you keep editing; archives are copies under their own prefix. See
-// docs/adr/0001-unprefixed-current-docs.md. The text transforms live in
-// `src/lib/buildtime/archive.ts` so they are typechecked and unit-tested; this
-// file is the filesystem wrapper around them.
-import fs from 'node:fs';
-import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-import {
-	rewriteDocsLinks,
-	freezeLastUpdated,
-	isInheritedRouteFile
-} from '../dist/buildtime/archive.js';
-
-const HELP = `svelte-docsmith — docs maintenance CLI
-
-Usage:
-  svelte-docsmith archive-version <id> [options]
-
-Freeze the current docs into an archived version folder. The archive keeps
-serving the release it documents while you go on editing the docs root.
-
-Options:
-  --label <label>  switcher label for the archive (default: the id)
-  --content <dir>  docs content directory (default: src/routes/docs)
-  --routes <dir>   SvelteKit routes directory (default: src/routes)
-`;
-
-// Written into every archive this command creates, so later runs know which
-// directories are already archives and must not be copied into the new one.
-const MARKER = '.docsmith-archive';
-
-const [command, ...rest] = process.argv.slice(2);
-
-if (command !== 'archive-version') {
-	console.log(HELP);
-	process.exit(command ? 1 : 0);
-}
-
-const opts = { content: 'src/routes/docs', routes: 'src/routes', label: undefined };
-let id;
-for (let i = 0; i < rest.length; i++) {
-	const arg = rest[i];
-	if (arg === '--label') opts.label = rest[++i];
-	else if (arg === '--content') opts.content = rest[++i];
-	else if (arg === '--routes') opts.routes = rest[++i];
-	else if (!arg.startsWith('--') && !id) id = arg;
-}
-
-const fail = (message) => {
-	console.error(`svelte-docsmith archive-version: ${message}`);
-	process.exit(1);
-};
-
-if (!id) fail('missing <id>. e.g. `svelte-docsmith archive-version v1`');
-// Must start alphanumeric: the id is both a directory name and a URL segment, so
-// `.`, `..` and dotfiles would escape the docs root or make a hidden, dead route.
-if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
-	fail(`invalid id: ${id}. Start with a letter or digit; it is used as a URL segment.`);
-}
-
-const contentDir = path.resolve(opts.content);
-const routesDir = path.resolve(opts.routes);
-const toDir = path.join(contentDir, id);
-const rel = (p) => path.relative(process.cwd(), p);
-
-if (!fs.existsSync(contentDir)) fail(`content directory not found: ${rel(contentDir)}`);
-if (fs.existsSync(toDir)) fail(`target already exists: ${rel(toDir)}`);
-
-// The docs URL base (e.g. `/docs`), derived exactly as the vite plugin does.
-const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
-
-/** Directories directly under the docs root that are already archives. */
-const archivedIds = new Set(
-	fs
-		.readdirSync(contentDir, { withFileTypes: true })
-		.filter((e) => e.isDirectory() && fs.existsSync(path.join(contentDir, e.name, MARKER)))
-		.map((e) => e.name)
-);
-
-const isPage = (name) => name.endsWith('+page.md') || name.endsWith('+page.svx');
-
-/** Copy the docs root into the archive, skipping what the archive shouldn't hold. */
-function copyCurrent(from, to) {
-	fs.mkdirSync(to, { recursive: true });
-	for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-		const src = path.join(from, entry.name);
-		const dest = path.join(to, entry.name);
-		if (entry.isDirectory()) {
-			// Never descend into the archive being written (it lives inside the docs
-			// root) or into an archive written by an earlier run.
-			if (src === toDir) continue;
-			if (from === contentDir && archivedIds.has(entry.name)) continue;
-			copyCurrent(src, dest);
-		} else {
-			// The root layout and error page already apply to the archive, which is
-			// nested inside them; copying them would nest a second DocsShell.
-			if (from === contentDir && isInheritedRouteFile(entry.name)) continue;
-			fs.copyFileSync(src, dest);
-		}
-	}
-}
-
-/** Every file in the archive, paired with the source file it was copied from. */
-function* eachCopiedFile(dir = toDir) {
-	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-		const file = path.join(dir, entry.name);
-		if (entry.isDirectory()) yield* eachCopiedFile(file);
-		else yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
+// Process boundary only. The command itself lives in
+// `src/lib/buildtime/cli/`, where it is typechecked and unit-tested; this file
+// exists so `svelte-docsmith` is a runnable bin entry.
+import { run, CliError } from '../dist/buildtime/cli/run.js';
+
+try {
+	run(process.argv.slice(2));
+} catch (error) {
+	if (error instanceof CliError) {
+		// A mistake the user can fix. The message says how; a stack would not help.
+		console.error(`svelte-docsmith: ${error.message}`);
+		process.exit(1);
 	}
+	throw error;
 }
-
-/** The date a page last really changed, so the archive doesn't claim today. */
-function lastCommitDate(file) {
-	try {
-		const out = execFileSync('git', ['log', '-1', '--format=%cs', '--', file], {
-			cwd: path.dirname(file),
-			encoding: 'utf-8',
-			stdio: ['ignore', 'pipe', 'ignore']
-		}).trim();
-		return out || undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-copyCurrent(contentDir, toDir);
-fs.writeFileSync(
-	path.join(toDir, MARKER),
-	`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
-		`This folder is frozen: edit the docs root instead.\n`
-);
-
-let pages = 0;
-for (const { file, source } of eachCopiedFile()) {
-	if (!isPage(path.basename(file))) continue;
-	pages++;
-	const text = fs.readFileSync(file, 'utf-8');
-	fs.writeFileSync(
-		file,
-		freezeLastUpdated(
-			rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }),
-			lastCommitDate(source)
-		)
-	);
-}
-
-const label = opts.label ?? id;
-console.log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
-console.log('Links were rewritten to stay inside the archive, and each page kept');
-console.log('its real last-updated date. Review the diff, then update');
-console.log('docsmith({ versions }) so the archive is served:\n');
-console.log('  versions: {');
-console.log("    current: { id: '<new release>', label: '<new release>' },");
-console.log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
-console.log('  }\n');

package/dist/buildtime/archives.d.ts

@@ -0,0 +1,18 @@
+import type { ArchivesOnDisk } from '../core/version.js';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export declare const ARCHIVE_MARKER = ".docsmith-archive";
+/** The text written into a new archive's marker file. */
+export declare function markerContents(id: string): string;
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export declare function discoverArchives(contentDir: string): ArchivesOnDisk;

package/dist/buildtime/archives.js

@@ -0,0 +1,43 @@
+/**
+ * What the docs root says about itself: which directories under it are archived
+ * versions. The scan is deliberately thin, so the reconciliation it feeds
+ * (`checkVersions`) stays pure and testable without a filesystem.
+ *
+ * Both callers cross this seam. The vite plugin scans before resolving versions;
+ * `archive-version` scans so it knows which directories not to copy into the
+ * archive it is writing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export const ARCHIVE_MARKER = '.docsmith-archive';
+/** The text written into a new archive's marker file. */
+export function markerContents(id) {
+    return (`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
+        `This folder is frozen: edit the docs root instead.\n` +
+        `Removing this file makes the build treat it as current-version content.\n`);
+}
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export function discoverArchives(contentDir) {
+    if (!fs.existsSync(contentDir))
+        return { marked: [], directories: [] };
+    const directories = fs
+        .readdirSync(contentDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    return {
+        directories,
+        marked: directories.filter((name) => fs.existsSync(path.join(contentDir, name, ARCHIVE_MARKER)))
+    };
+}

package/dist/buildtime/cli/archive-version.d.ts

@@ -0,0 +1,18 @@
+export type ArchiveVersionOptions = {
+    /** Id of the archive to create. Becomes its directory name and URL segment. */
+    id: string;
+    /** Switcher label for the archive. Defaults to the id. */
+    label?: string;
+    /** Docs content directory, resolved against `cwd`. */
+    content?: string;
+    /** SvelteKit routes directory, resolved against `cwd`. */
+    routes?: string;
+    /** Working directory the relative options resolve against. */
+    cwd?: string;
+};
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export declare function archiveVersion(options: ArchiveVersionOptions, log: (line: string) => void): number;

package/dist/buildtime/cli/archive-version.js

@@ -0,0 +1,104 @@
+/**
+ * `svelte-docsmith archive-version <id>`: freeze the current docs into an
+ * archived version folder so they keep serving the release they document while
+ * the docs root goes on being edited.
+ *
+ * The pure text transforms live in `../archive.js`; this is the filesystem work
+ * around them. It takes its working directory and its output sink rather than
+ * reading `process.cwd()` and calling `console.log`, so the whole command runs
+ * in-process under test. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertValidVersionId } from '../../core/version.js';
+import { freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
+import { ARCHIVE_MARKER, discoverArchives, markerContents } from '../archives.js';
+import { lastCommitDate } from '../git.js';
+import { docsBaseFrom } from '../paths.js';
+import { isPageFile } from '../vite/pages.js';
+import { CliError } from './error.js';
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export function archiveVersion(options, log) {
+    const cwd = options.cwd ?? process.cwd();
+    const { id, label = options.id } = options;
+    try {
+        assertValidVersionId(id);
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+    const contentDir = path.resolve(cwd, options.content ?? 'src/routes/docs');
+    const routesDir = path.resolve(cwd, options.routes ?? 'src/routes');
+    const toDir = path.join(contentDir, id);
+    const rel = (p) => path.relative(cwd, p);
+    if (!fs.existsSync(contentDir)) {
+        throw new CliError(`content directory not found: ${rel(contentDir)}`);
+    }
+    if (fs.existsSync(toDir)) {
+        throw new CliError(`target already exists: ${rel(toDir)}`);
+    }
+    const docsBase = docsBaseFrom(routesDir, contentDir);
+    // Archives already on disk, so this run neither copies them into the new
+    // archive nor rewrites links that already point into one of them.
+    const archivedIds = new Set(discoverArchives(contentDir).marked);
+    /** Copy the docs root into the archive, skipping what the archive shouldn't hold. */
+    function copyCurrent(from, to) {
+        fs.mkdirSync(to, { recursive: true });
+        for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+            const src = path.join(from, entry.name);
+            const dest = path.join(to, entry.name);
+            if (entry.isDirectory()) {
+                // Never descend into the archive being written (it lives inside the docs
+                // root) or into an archive written by an earlier run.
+                if (src === toDir)
+                    continue;
+                if (from === contentDir && archivedIds.has(entry.name))
+                    continue;
+                copyCurrent(src, dest);
+            }
+            else {
+                // The root layout and error page already apply to the archive, which is
+                // nested inside them; copying them would nest a second DocsShell.
+                if (from === contentDir && isInheritedRouteFile(entry.name))
+                    continue;
+                fs.copyFileSync(src, dest);
+            }
+        }
+    }
+    /** Every file in the archive, paired with the source file it was copied from. */
+    function* eachCopiedFile(dir = toDir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                yield* eachCopiedFile(file);
+            else
+                yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
+        }
+    }
+    copyCurrent(contentDir, toDir);
+    fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
+    let pages = 0;
+    for (const { file, source } of eachCopiedFile()) {
+        if (!isPageFile(path.basename(file)))
+            continue;
+        pages++;
+        const text = fs.readFileSync(file, 'utf-8');
+        fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), lastCommitDate(source)));
+    }
+    log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
+    log('Links were rewritten to stay inside the archive, and each page kept');
+    log('its real last-updated date. Review the diff, then update');
+    log('docsmith({ versions }) so the archive is served:\n');
+    log('  versions: {');
+    log("    current: { id: '<new release>', label: '<new release>' },");
+    log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
+    log('  }\n');
+    // Until that paste lands the build fails, by design: the archive is on disk
+    // and undeclared. See docs/adr/0003-the-archive-marker-defines-an-archive.md.
+    log('Until then the build will fail, reporting this archive as undeclared.\n');
+    return pages;
+}

package/dist/buildtime/cli/error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export declare class CliError extends Error {
+    readonly name = "CliError";
+}

package/dist/buildtime/cli/error.js

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export class CliError extends Error {
+    name = 'CliError';
+}

package/dist/buildtime/cli/run.d.ts

@@ -0,0 +1,13 @@
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export declare const HELP = "svelte-docsmith \u2014 docs maintenance CLI\n\nUsage:\n  svelte-docsmith archive-version <id> [options]\n\nFreeze the current docs into an archived version folder. The archive keeps\nserving the release it documents while you go on editing the docs root.\n\nOptions:\n  --label <label>  switcher label for the archive (default: the id)\n  --content <dir>  docs content directory (default: src/routes/docs)\n  --routes <dir>   SvelteKit routes directory (default: src/routes)\n";
+/** Where the command writes, and what it resolves relative paths against. */
+export type CliIo = {
+    cwd?: string;
+    log?: (line: string) => void;
+};
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export declare function run(argv: string[], io?: CliIo): void;

package/dist/buildtime/cli/run.js

@@ -0,0 +1,62 @@
+/**
+ * The `svelte-docsmith` maintenance CLI. Currently one command:
+ * `archive-version`.
+ *
+ * This is the whole command, not a helper for it: `bin/svelte-docsmith.mjs` is a
+ * shim that hands over `process.argv` and turns a thrown {@link CliError} into a
+ * message and an exit code. Keeping the process boundary out here means the
+ * command is typechecked, and testable in-process against a temporary directory
+ * rather than by spawning node and parsing stdout.
+ */
+import { archiveVersion } from './archive-version.js';
+import { CliError } from './error.js';
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export const HELP = `svelte-docsmith — docs maintenance CLI
+
+Usage:
+  svelte-docsmith archive-version <id> [options]
+
+Freeze the current docs into an archived version folder. The archive keeps
+serving the release it documents while you go on editing the docs root.
+
+Options:
+  --label <label>  switcher label for the archive (default: the id)
+  --content <dir>  docs content directory (default: src/routes/docs)
+  --routes <dir>   SvelteKit routes directory (default: src/routes)
+`;
+/** Parse `archive-version`'s flags and its one positional id. */
+function parseArchiveArgs(rest) {
+    const options = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--label')
+            options.label = rest[++i];
+        else if (arg === '--content')
+            options.content = rest[++i];
+        else if (arg === '--routes')
+            options.routes = rest[++i];
+        else if (!arg.startsWith('--') && !options.id)
+            options.id = arg;
+    }
+    if (!options.id) {
+        throw new CliError('missing <id>. e.g. `svelte-docsmith archive-version v1`');
+    }
+    return options;
+}
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export function run(argv, io = {}) {
+    const log = io.log ?? ((line) => console.log(line));
+    const [command, ...rest] = argv;
+    if (!command) {
+        log(HELP);
+        return;
+    }
+    if (command !== 'archive-version') {
+        throw new CliError(`unknown command: ${command}\n\n${HELP}`);
+    }
+    archiveVersion({ ...parseArchiveArgs(rest), cwd: io.cwd }, log);
+}

package/dist/buildtime/{vite/git.d.ts → git.d.ts}

@@ -1,4 +1,4 @@
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export declare function lastCommitDate(file: string): string | undefined;
 /**
  * Release dates keyed by version, read from the commit that introduced each

package/dist/buildtime/{vite/git.js → git.js}

@@ -1,8 +1,20 @@
+/**
+ * The git queries the build makes: when a page last changed, and when each
+ * release landed. Used by both the vite plugin and the `archive-version`
+ * command, which is why it sits here rather than under `vite/`.
+ *
+ * Every date here is `%cs`, the commit's calendar day (`YYYY-MM-DD`), never a
+ * timestamp. Dates from this module are rendered as a day and nothing more, and
+ * a date-only string parses to UTC midnight, so pinning the formatter to UTC
+ * renders the committer's own day identically for every reader and identically
+ * on the server and the client. A full timestamp buys precision no consumer
+ * uses and reintroduces the day-boundary drift.
+ */
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export function lastCommitDate(file) {
-    const res = spawnSync('git', ['log', '-1', '--format=%cI', '--', file], {
+    const res = spawnSync('git', ['log', '-1', '--format=%cs', '--', file], {
         cwd: path.dirname(file),
         encoding: 'utf-8'
     });
@@ -19,7 +31,7 @@ export function changelogDates(file) {
     const dates = new Map();
     // `-L` would be per-line; instead walk the file's commits newest-first and
     // record the first commit in which each version heading appears.
-    const log = spawnSync('git', ['log', '--format=%H %cI', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
+    const log = spawnSync('git', ['log', '--format=%H %cs', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
     if (log.status !== 0)
         return dates;
     for (const line of log.stdout.trim().split('\n').filter(Boolean)) {

package/dist/buildtime/paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. This is the same mapping the collectors use to turn a
+ * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
+ * served at `/docs/intro` under a base of `/docs`.
+ */
+export declare function docsBaseFrom(routesDir: string, contentDir: string): string;

package/dist/buildtime/paths.js

@@ -0,0 +1,15 @@
+/**
+ * Build-time path derivations shared by the vite plugin and the maintenance CLI.
+ * Both have to agree on where the docs live in URL space, and each deriving it
+ * separately is how they drift.
+ */
+import path from 'node:path';
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. This is the same mapping the collectors use to turn a
+ * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
+ * served at `/docs/intro` under a base of `/docs`.
+ */
+export function docsBaseFrom(routesDir, contentDir) {
+    return '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+}

package/dist/buildtime/vite/collect.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { listPageFiles } from './pages.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { extractLlmsContent, extractSearchText, extractToc, readingMinutes } from './extract.js';
-import { lastCommitDate } from './git.js';
+import { lastCommitDate } from '../git.js';
 /**
  * Read a page's `section` frontmatter: a string is one level, an array is a
  * nested group path. Non-string array members are dropped; anything else is

package/dist/buildtime/vite/index.js

@@ -19,7 +19,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
-import { resolveVersions } from '../../core/version.js';
+import { checkVersions, resolveVersions } from '../../core/version.js';
+import { ARCHIVE_MARKER, discoverArchives } from '../archives.js';
+import { docsBaseFrom } from '../paths.js';
 import { isPageFile, listPageFiles } from './pages.js';
 import { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
 import { collectReleases } from './releases.js';
@@ -49,9 +51,7 @@ function contentIndexPlugin(options) {
     const contentDir = path.resolve(options.content ?? 'src/routes/docs');
     const routesDir = path.resolve(options.routes ?? 'src/routes');
     const versions = options.versions;
-    // The docs URL base, e.g. `/docs`, derived from the content dir's location
-    // under the routes dir — the same mapping `collect.ts` uses for page URLs.
-    const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+    const docsBase = docsBaseFrom(routesDir, contentDir);
     const changelogFile = options.changelog === false ? undefined : path.resolve(options.changelog ?? 'CHANGELOG.md');
     const changelogRoute = options.changelogPath ?? '/changelog';
     const changelogOverrides = path.join(routesDir, changelogRoute.replace(/^\//, ''));
@@ -76,6 +76,11 @@ function contentIndexPlugin(options) {
             if (id === VIRTUAL_CONTENT_ID) {
                 for (const file of listPageFiles(contentDir))
                     this.addWatchFile(file);
+                // Before anything is collected: a config that disagrees with the docs
+                // root produces an index that is wrong rather than empty, so it has to
+                // fail here rather than render. Re-runs on invalidation, so archiving
+                // during `dev` reports immediately.
+                checkVersions(versions, discoverArchives(contentDir), ARCHIVE_MARKER);
                 const docs = collectDocs(contentDir, routesDir, versions);
                 const resolved = resolveVersions(versions, docsBase, docs);
                 return (`export const docs = ${JSON.stringify(docs, null, 2)};\n` +

package/dist/buildtime/vite/releases.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { marked } from 'marked';
 import { parseChangelog } from '../changelog.js';
-import { changelogDates } from './git.js';
+import { changelogDates } from '../git.js';
 /**
  * Render an entry's markdown to HTML at build time. Changesets entries use
  * inline code, emphasis, links and nested lists, so shipping the raw markdown

package/dist/components/changelog/changelog-entry.svelte

@@ -3,12 +3,17 @@
 
 	const { release }: { release: ChangelogRelease } = $props();
 
+	// `timeZone: 'UTC'` is not cosmetic. `release.date` is a calendar day, which
+	// parses to UTC midnight, so formatting in the ambient zone shifts it a day
+	// west of UTC — and shifts it on the client but not on the server, so the
+	// rendered date changes under hydration.
 	const formatted = $derived(
 		release.date
 			? new Date(release.date).toLocaleDateString('en-US', {
 					year: 'numeric',
 					month: 'long',
-					day: 'numeric'
+					day: 'numeric',
+					timeZone: 'UTC'
 				})
 			: undefined
 	);

package/dist/components/chrome/search.svelte

@@ -2,6 +2,7 @@
 	import { goto } from '$app/navigation';
 	import * as Command from '../shadcn/command/index.js';
 	import { useSearch } from '../../search/context.svelte.js';
+	import { useDocsPage } from '../docs-page-context.js';
 	import type { SearchDoc } from '../../core/index.js';
 	import type { SearchEngine } from '../../search/create-search.js';
 	import CornerDownLeft from '@lucide/svelte/icons/corner-down-left';
@@ -26,6 +27,10 @@
 	} = $props();
 
 	const search = useSearch();
+	// The version being read, straight off the shell's resolved page view, so
+	// results and the cached engine follow the reader across a version switch.
+	const docsPage = useDocsPage();
+	const activeVersion = $derived(docsPage.view.activeVersionId);
 
 	let query = $state('');
 	let engine = $state<SearchEngine | null>(null);
@@ -36,14 +41,12 @@
 	let engineVersion: string | undefined;
 
 	const trimmed = $derived(query.trim());
-	// Scope to the active version when the shell set one (versioned sites).
-	const results = $derived(
-		engine && trimmed ? engine.search(query, undefined, search?.version) : []
-	);
+	// Scope to the active version on a versioned site; `undefined` otherwise.
+	const results = $derived(engine && trimmed ? engine.search(query, undefined, activeVersion) : []);
 
 	// Build the index the first time the palette opens; keep it for later opens.
 	async function ensureEngine() {
-		const version = search?.version;
+		const version = activeVersion;
 		if ((engine && engineVersion === version) || status === 'loading') return;
 		status = 'loading';
 		try {