blume 0.6.7 → 0.8.0

package/src/core/manifest.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "./base-path.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type {
@@ -26,6 +27,64 @@ export const contentIndexable = (
   !page.meta.search.exclude &&
   (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
 
+/**
+ * Fallback materialization: render the fallback locale's content at the
+ * localized URL for any translation a non-default locale is missing, so static
+ * output is fully prerendered (render-fallback, no client redirect). Fallback
+ * routes are not indexed and carry no `hreflang` of their own.
+ */
+const buildFallbackRoutes = (
+  graph: ContentGraph,
+  i18n: NonNullable<ResolvedConfig["i18n"]>,
+  alternatesByKey: Map<string, RouteAlternate[]>,
+  basePath: string
+): RouteManifestEntry[] => {
+  const fallback = resolveFallbackLocale(i18n);
+  if (!fallback) {
+    return [];
+  }
+  const fallbackPages = new Map(
+    graph.pages.flatMap((page) =>
+      page.locale === fallback ? [[page.translationKey, page] as const] : []
+    )
+  );
+  const routes: RouteManifestEntry[] = [];
+  for (const { code } of i18n.locales) {
+    if (code === fallback) {
+      continue;
+    }
+    const present = new Set(
+      graph.pages.flatMap((page) =>
+        page.locale === code ? [page.translationKey] : []
+      )
+    );
+    for (const [key, source] of fallbackPages) {
+      if (present.has(key)) {
+        continue;
+      }
+      routes.push({
+        alternates: alternatesByKey.get(key) ?? [],
+        collection: source.collection ?? "docs",
+        contentType: source.contentType,
+        draft: source.meta.draft,
+        editUrl: source.editUrl,
+        entryId: source.entryId ?? source.source.ref,
+        fallback: true,
+        hidden: source.meta.sidebar.hidden,
+        id: source.id,
+        indexable: false,
+        lastModified: source.lastModified,
+        locale: code,
+        path: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        source: source.source,
+        sourcePath: source.sourcePath,
+        title: source.title,
+      });
+    }
+  }
+  return routes;
+};
+
 /** Build the runtime manifest that bridges core and the generated Astro app. */
 export const buildManifest = (options: {
   context: ProjectContext;
@@ -65,52 +124,10 @@ export const buildManifest = (options: {
     title: page.title,
   }));
 
-  // Fallback materialization: render the fallback locale's content at the
-  // localized URL for any translation a non-default locale is missing, so static
-  // output is fully prerendered (render-fallback, no client redirect). Fallback
-  // routes are not indexed and carry no `hreflang` of their own.
   if (i18n) {
-    const fallback = resolveFallbackLocale(i18n);
-    if (fallback) {
-      const fallbackPages = new Map(
-        graph.pages
-          .filter((page) => page.locale === fallback)
-          .map((page) => [page.translationKey, page] as const)
-      );
-      for (const { code } of i18n.locales) {
-        if (code === fallback) {
-          continue;
-        }
-        const present = new Set(
-          graph.pages
-            .filter((page) => page.locale === code)
-            .map((page) => page.translationKey)
-        );
-        for (const [key, source] of fallbackPages) {
-          if (present.has(key)) {
-            continue;
-          }
-          routes.push({
-            alternates: alternatesByKey.get(key) ?? [],
-            collection: source.collection ?? "docs",
-            contentType: source.contentType,
-            draft: source.meta.draft,
-            editUrl: source.editUrl,
-            entryId: source.entryId ?? source.source.ref,
-            fallback: true,
-            hidden: source.meta.sidebar.hidden,
-            id: source.id,
-            indexable: false,
-            lastModified: source.lastModified,
-            locale: code,
-            path: localizeRoute(key, code, i18n),
-            source: source.source,
-            sourcePath: source.sourcePath,
-            title: source.title,
-          });
-        }
-      }
-    }
+    routes.push(
+      ...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath)
+    );
   }
 
   routes.sort((a, b) => a.path.localeCompare(b.path));

package/src/core/nav-diagnostics.ts

@@ -157,7 +157,7 @@ const hiddenInSidebarDiagnostics = (
   pages: PageRecord[]
 ): Diagnostic[] => {
   const hidden = new Set(
-    pages.filter((page) => page.meta.sidebar.hidden).map((page) => page.id)
+    pages.flatMap((page) => (page.meta.sidebar.hidden ? [page.id] : []))
   );
   if (hidden.size === 0) {
     return [];

package/src/core/navigation.ts

@@ -1,5 +1,6 @@
 import { extname } from "pathe";
 
+import { stripBasePath, withBasePath } from "./base-path.ts";
 import type {
   FolderMeta,
   SidebarDisplay,
@@ -28,7 +29,7 @@ const humanize = (segment: string): string =>
 
 const numericOrder = (segment: string): number => {
   const value = segment.match(NUMERIC_PREFIX)?.groups?.order;
-  return value ? Number.parseInt(value, 10) : Number.POSITIVE_INFINITY;
+  return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
 };
 
 /** The nav key of a raw path segment: group label or numeric-stripped name. */
@@ -37,6 +38,14 @@ const segmentKey = (raw: string): string => {
   return (group ?? raw).replace(NUMERIC_PREFIX, "");
 };
 
+/**
+ * Whether a filename stem is a directory index, ignoring an ordering prefix:
+ * route mapping strips the prefix before dropping `index`, so `01-index` routes
+ * exactly like `index` and must be treated as one here too.
+ */
+const isIndexStem = (stem: string): boolean =>
+  stem.replace(NUMERIC_PREFIX, "") === "index";
+
 interface MutablePage {
   kind: "page";
   key: string;
@@ -105,7 +114,7 @@ const pageOrder = (page: PageRecord, filename: string): number => {
   if (page.meta.sidebar.order !== undefined) {
     return page.meta.sidebar.order;
   }
-  if (filename.replace(extname(filename), "") === "index") {
+  if (isIndexStem(filename.replace(extname(filename), ""))) {
     return Number.NEGATIVE_INFINITY;
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
@@ -276,8 +285,9 @@ const buildFileSystemSidebar = (
     // An index page's route IS its folder's route (no page segment to drop),
     // and `(group)` folders contribute no route segment at all.
     const routeSegments = page.route.split("/").filter(Boolean);
-    const folderParts =
-      stem === "index" ? routeSegments : routeSegments.slice(0, -1);
+    const folderParts = isIndexStem(stem)
+      ? routeSegments
+      : routeSegments.slice(0, -1);
     const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
 
@@ -326,82 +336,100 @@ const normalizeRef = (ref: string): string => {
 
 const routeForRef = (
   ref: string | undefined,
-  byRoute: Map<string, PageRecord>
+  byRoute: Map<string, PageRecord>,
+  basePath: string
 ): string | undefined => {
   if (!ref) {
     return undefined;
   }
   const normalized = normalizeRef(ref);
-  return byRoute.get(normalized)?.route ?? normalized;
+  // A matched page carries an already-based `route`; an unmatched ref is an
+  // author-written root-relative path that still needs the base applied.
+  return byRoute.get(normalized)?.route ?? withBasePath(basePath, normalized);
+};
+
+/**
+ * Convert one non-group explicit-config sidebar item (string ref, `root`, or
+ * `href`) to a nav node, or null to skip. Group items (`item.items`) are handled
+ * by `buildConfigSidebar` itself so it owns the recursion.
+ */
+const configItemToNode = (
+  item: SidebarItemConfig,
+  byRoute: Map<string, PageRecord>,
+  basePath: string
+): NavNode | null => {
+  if (typeof item === "string") {
+    const page = byRoute.get(normalizeRef(item));
+    if (!page) {
+      return null;
+    }
+    return {
+      badge: page.meta.sidebar.badge,
+      deprecated: page.meta.deprecated || undefined,
+      description: page.description,
+      icon: page.meta.sidebar.icon,
+      kind: "page",
+      label: page.meta.sidebar.label ?? page.title,
+      pageId: page.id,
+      route: page.route,
+    };
+  }
+
+  if (item.root) {
+    const page = byRoute.get(normalizeRef(item.root));
+    return {
+      badge: item.badge,
+      deprecated: page?.meta.deprecated || undefined,
+      icon: item.icon,
+      kind: "page",
+      label: item.label,
+      pageId: page?.id ?? "",
+      route: page?.route ?? withBasePath(basePath, normalizeRef(item.root)),
+    };
+  }
+
+  if (item.href) {
+    return {
+      badge: item.badge,
+      icon: item.icon,
+      kind: "page",
+      label: item.label,
+      pageId: "",
+      route: withBasePath(basePath, item.href),
+    };
+  }
+
+  return null;
 };
 
 /** Build the sidebar tree from an explicit config spec. */
 const buildConfigSidebar = (
   items: SidebarItemConfig[],
   byRoute: Map<string, PageRecord>,
-  display: SidebarDisplay
+  display: SidebarDisplay,
+  basePath: string
 ): NavNode[] => {
   const nodes: NavNode[] = [];
-
   for (const item of items) {
-    if (typeof item === "string") {
-      const page = byRoute.get(normalizeRef(item));
-      if (page) {
-        nodes.push({
-          badge: page.meta.sidebar.badge,
-          deprecated: page.meta.deprecated || undefined,
-          description: page.description,
-          icon: page.meta.sidebar.icon,
-          kind: "page",
-          label: page.meta.sidebar.label ?? page.title,
-          pageId: page.id,
-          route: page.route,
-        });
-      }
-      continue;
-    }
-
-    if (item.items) {
+    if (typeof item !== "string" && item.items) {
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display),
+        children: buildConfigSidebar(item.items, byRoute, display, basePath),
         collapsed: item.collapsed,
         directory: item.directory,
         display: item.display ?? display,
         icon: item.icon,
         kind: "group",
         label: item.label,
-        route: routeForRef(item.root, byRoute),
-      });
-      continue;
-    }
-
-    if (item.root) {
-      const page = byRoute.get(normalizeRef(item.root));
-      nodes.push({
-        badge: item.badge,
-        deprecated: page?.meta.deprecated || undefined,
-        icon: item.icon,
-        kind: "page",
-        label: item.label,
-        pageId: page?.id ?? "",
-        route: page?.route ?? normalizeRef(item.root),
+        route: routeForRef(item.root, byRoute, basePath),
       });
       continue;
     }
-
-    if (item.href) {
-      nodes.push({
-        badge: item.badge,
-        icon: item.icon,
-        kind: "page",
-        label: item.label,
-        pageId: "",
-        route: item.href,
-      });
+    const node = configItemToNode(item, byRoute, basePath);
+    if (node) {
+      nodes.push(node);
     }
   }
-
   return nodes;
 };
 
@@ -409,6 +437,8 @@ const buildConfigSidebar = (
 export const buildNavigation = (
   pages: PageRecord[],
   options: {
+    /** Site-wide route mount point (`""` or `/seg`); applied to config paths. */
+    basePath?: string;
     folderMeta: Map<string, FolderMeta>;
     /** Global display mode for every sidebar group (default `flat`). */
     display?: SidebarDisplay;
@@ -426,30 +456,84 @@ export const buildNavigation = (
     refByLogical?: boolean;
     /** Shared `meta.$.*` meta, keyed by locale-stripped dir path. */
     sharedFolderMeta?: Map<string, FolderMeta>;
+    /**
+     * The tree's root route before `basePath` (`"/"`, or the locale prefix
+     * under i18n, e.g. `/fr` — tab paths arrive already localized). The tab
+     * pointing here spans the whole tree, so it is excluded from tab-section
+     * scoping.
+     */
+    localizedRoot?: string;
   }
 ): Navigation => {
-  const featured = options.featured ?? [];
-  const selectors = options.selectors ?? [];
-  const tabs = options.tabs ?? [];
+  const basePath = options.basePath ?? "";
   const display = options.display ?? "flat";
   const metaPrefix = options.metaPrefix ?? "";
   const sharedFolderMeta = options.sharedFolderMeta ?? new Map();
+
+  // Config-provided nav paths are authored as if mounted at root, so the base
+  // is applied here (idempotently, and only to internal paths — external URLs
+  // pass through). Content-derived sidebar routes are already based via
+  // `page.route`. The based tab paths also feed tab-scoping below, so they must
+  // agree with the based content routes. With no base, this is a pure pass-
+  // through — the arrays keep their exact authored shape.
+  const rebasePath = <T extends { path: string }>(item: T): T => ({
+    ...item,
+    path: withBasePath(basePath, item.path),
+  });
+  const featured = basePath
+    ? (options.featured ?? []).map((link) => ({
+        ...link,
+        href: withBasePath(basePath, link.href),
+      }))
+    : (options.featured ?? []);
+  const selectors = basePath
+    ? (options.selectors ?? []).map((selector) => ({
+        ...selector,
+        items: selector.items.map(rebasePath),
+      }))
+    : (options.selectors ?? []);
+  const tabs = basePath
+    ? (options.tabs ?? []).map((tab) => ({
+        ...tab,
+        items: tab.items?.map(rebasePath),
+        path: withBasePath(basePath, tab.path),
+      }))
+    : (options.tabs ?? []);
   const byRoute = new Map(
     pages.map((page) => [
       options.refByLogical ? page.translationKey : page.route,
       page,
     ])
   );
+  // Explicit-sidebar refs (`"foo/index"`) are authored as if mounted at root,
+  // but `page.route` carries the base — alias each page under its base-less
+  // route so a bare ref still resolves. (The i18n `refByLogical` map is already
+  // keyed by the base-less `translationKey`, so it needs no alias.)
+  if (basePath && !options.refByLogical) {
+    for (const page of pages) {
+      const bare = stripBasePath(basePath, page.route);
+      if (!byRoute.has(bare)) {
+        byRoute.set(bare, page);
+      }
+    }
+  }
 
   if (options.sidebar) {
     return {
       featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute, display),
+      sidebar: buildConfigSidebar(options.sidebar, byRoute, display, basePath),
       tabs,
     };
   }
 
+  // A tab pointing at the tree root spans the whole sidebar rather than one
+  // section, so it must not feed tab-section hoisting. `tabs` carries final
+  // paths (localized, then based), so the root is compared in the same space —
+  // a root-level `(group)` folder's routePath is exactly the based/localized
+  // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
+  // under a base, falsely scope a group named like the prefix).
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   return {
     featured,
     selectors,
@@ -459,7 +543,9 @@ export const buildNavigation = (
       sharedFolderMeta,
       metaPrefix,
       display,
-      new Set(tabs.map((tab) => tab.path).filter((path) => path !== "/"))
+      new Set(
+        tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+      )
     ),
     tabs,
   };

package/src/core/package-json.ts

@@ -15,8 +15,22 @@ export const toPackageName = (raw: string): string =>
  * dependency pinned to the installed version plus `dev`/`build`/`doctor`
  * scripts, so `npm install && npm run dev` works immediately. Shared by
  * `blume init` and the migrators, which scaffold one when a project has none.
+ * `extraDeps` adds source SDKs (e.g. `@notionhq/client`) beside `blume`.
  */
-export const blumePackageJson = (name: string): string => `{
+export const blumePackageJson = (
+  name: string,
+  extraDeps: Record<string, string> = {}
+): string => {
+  const dependencies = Object.entries({
+    blume: `^${getBlumeVersion()}`,
+    ...extraDeps,
+  })
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .map(
+      ([dep, range]) => `    ${JSON.stringify(dep)}: ${JSON.stringify(range)}`
+    )
+    .join(",\n");
+  return `{
   "name": ${JSON.stringify(name)},
   "private": true,
   "type": "module",
@@ -26,7 +40,8 @@ export const blumePackageJson = (name: string): string => `{
     "doctor": "blume doctor"
   },
   "dependencies": {
-    "blume": "^${getBlumeVersion()}"
+${dependencies}
   }
 }
 `;
+};

package/src/core/project-graph.ts

@@ -1,6 +1,7 @@
 import { relative } from "pathe";
 
 import { loadConfig } from "./config.ts";
+import { applyDeploymentEnv } from "./deployment-env.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import {
@@ -108,7 +109,7 @@ const entryIdDiagnostics = (
         message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
         severity: "error",
         suggestion:
-          "Give each filesystem source a root under content.root, or use a single filesystem source so the collection can root at it.",
+          "Use a single filesystem source (the docs collection roots at it), or root every filesystem source at content.root and partition them with include globs — a root at a subdirectory of content.root still mismatches.",
       });
     }
   }
@@ -139,7 +140,13 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  const config = applyConfigOverrides(configResult.config, options.overrides);
+  // Re-run platform detection after CLI overrides: `loadConfig` already ran it,
+  // but adapter inference keys off `deployment.output`, which `--output server`
+  // only sets here. Idempotent for already-resolved fields — `deployment.site`
+  // keeps loadConfig's explicit > platform env > devServerUrl precedence.
+  const config = applyDeploymentEnv(
+    applyConfigOverrides(configResult.config, options.overrides)
+  );
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
@@ -158,12 +165,11 @@ export const scanProject = async (
   // Folder meta is discovered per filesystem source, under each source's own
   // root and keyed by its route prefix, so a prefixed/root-differing source's
   // `meta.ts` still lines up with its (prefixed) sidebar group path.
-  const metaSources: FolderMetaSource[] = sources
-    .filter((source) => !source.staged && source.contentRoot)
-    .map((source) => ({
-      prefix: source.prefix,
-      root: source.contentRoot ?? "",
-    }));
+  const metaSources: FolderMetaSource[] = sources.flatMap((source) =>
+    source.staged || !source.contentRoot
+      ? []
+      : [{ prefix: source.prefix, root: source.contentRoot }]
+  );
 
   // Run every source's `load()` in parallel, then funnel each entry through the
   // shared `normalizeEntry` so route mapping is identical regardless of origin.
@@ -172,9 +178,9 @@ export const scanProject = async (
   // `discoverFolderMeta`).
   const localeDirs =
     config.i18n && config.i18n.parser === "dir"
-      ? config.i18n.locales
-          .map((locale) => locale.code)
-          .filter((code) => code !== config.i18n?.defaultLocale)
+      ? config.i18n.locales.flatMap((locale) =>
+          locale.code === config.i18n?.defaultLocale ? [] : [locale.code]
+        )
       : undefined;
 
   const [loaded, folderMeta] = await Promise.all([
@@ -190,6 +196,7 @@ export const scanProject = async (
     contentDiagnostics.push(...diagnostics);
     for (const entry of entries) {
       const normalized = normalizeEntry(entry, {
+        basePath: config.basePath,
         defaultType: config.content.defaultType,
         i18n: config.i18n,
         source: {
@@ -217,11 +224,13 @@ export const scanProject = async (
     const fsPaths = pages
       .map((page) => page.sourcePath)
       .filter((path): path is string => path !== undefined);
-    const gitTimes = gitLastModifiedTimes(
-      context.root,
-      context.contentRoot,
-      fsPaths
+    // The git pathspecs must cover where the pages actually live: each
+    // filesystem source's own root, which diverges from the global
+    // `content.root` when a source configures a non-default `root`.
+    const contentRoots = sources.flatMap((source) =>
+      source.staged || !source.contentRoot ? [] : [source.contentRoot]
     );
+    const gitTimes = gitLastModifiedTimes(context.root, contentRoots, fsPaths);
     for (const page of pages) {
       if (!page.lastModified && page.sourcePath) {
         page.lastModified = gitTimes.get(page.sourcePath);
@@ -230,6 +239,7 @@ export const scanProject = async (
   }
 
   const graph = buildContentGraph(pages, {
+    basePath: config.basePath,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,