@supatent/supatent-docs 0.1.0

package/runtime/src/framework/runtime-locales.ts

@@ -0,0 +1,85 @@
+import { cache } from "react";
+import { createClient } from "@supatent/client";
+import { docsConfig } from "../docs.config";
+import type { DocsDataMode } from "./types";
+
+export type RuntimeLocales = {
+  defaultLocale: string;
+  locales: string[];
+};
+
+type RuntimeLocalesOptions = {
+  dataMode?: DocsDataMode;
+};
+
+function normalizeLocales(locales: string[]): string[] {
+  const unique = new Set<string>();
+
+  for (const locale of locales) {
+    const normalized = locale.trim();
+    if (normalized) {
+      unique.add(normalized);
+    }
+  }
+
+  return [...unique];
+}
+
+function resolveConfiguredRuntimeLocales(): RuntimeLocales {
+  const locales = normalizeLocales(docsConfig.routing.locales);
+  const fallbackDefault = docsConfig.routing.defaultLocale;
+  const hasDefault = locales.includes(fallbackDefault);
+  const defaultLocale = hasDefault ? fallbackDefault : (locales[0] ?? fallbackDefault);
+
+  return {
+    defaultLocale,
+    locales: locales.length > 0 ? locales : [fallbackDefault],
+  };
+}
+
+async function fetchRuntimeLocales(): Promise<RuntimeLocales> {
+  const client = createClient({
+    baseUrl: docsConfig.supatent.baseUrl,
+    projectSlug: docsConfig.supatent.projectSlug,
+    apiKey: docsConfig.supatent.apiKey,
+    // Locales are project metadata and should not depend on draft/published data mode.
+    preview: false,
+    cache: docsConfig.supatent.cache,
+  });
+
+  try {
+    const response = await client.getLocales();
+    const locales = normalizeLocales(response.locales.map((entry) => entry.code));
+
+    if (locales.length === 0) {
+      throw new Error("Supatent returned no locales.");
+    }
+
+    const defaultLocale = locales.includes(response.default)
+      ? response.default
+      : locales[0];
+
+    return {
+      defaultLocale,
+      locales,
+    };
+  } catch (error) {
+    const fallback = resolveConfiguredRuntimeLocales();
+    const reason = error instanceof Error ? error.message : "Unknown locale fetch failure";
+    console.warn(
+      `[supatent-docs] Locale metadata fetch failed (${reason}). Falling back to configured locales: ${fallback.locales.join(", ")}.`,
+    );
+    return fallback;
+  }
+}
+
+const getPublishedRuntimeLocales = cache(async (): Promise<RuntimeLocales> =>
+  fetchRuntimeLocales(),
+);
+
+export async function getRuntimeLocales(
+  options: RuntimeLocalesOptions = {},
+): Promise<RuntimeLocales> {
+  void options;
+  return getPublishedRuntimeLocales();
+}

package/runtime/src/framework/search-index-types.ts

@@ -0,0 +1,34 @@
+export const DEFAULT_SEARCH_INDEX_OUTPUT_DIR = "public/.supatent-docs/search";
+export const SEARCH_INDEX_PUBLIC_BASE_PATH = "/.supatent-docs/search";
+
+export type SearchIndexDocument = {
+  id: string;
+  locale: string;
+  slug: string;
+  title: string;
+  path: string;
+  order: number;
+  plainText: string;
+};
+
+export type LocaleSearchIndexPayload = {
+  locale: string;
+  generatedAt: string;
+  documents: SearchIndexDocument[];
+};
+
+export type SearchIndexManifestEntry = {
+  locale: string;
+  file: string;
+  hash: string;
+  documentCount: number;
+};
+
+export type SearchIndexManifest = {
+  version: 1;
+  generatedAt: string;
+  defaultLocale: string;
+  basePath: string;
+  outputDir: string;
+  entries: SearchIndexManifestEntry[];
+};

package/runtime/src/framework/search-index.ts

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  createClient,
+  type ContentItem,
+  type SupatentClient,
+} from "@supatent/client";
+import { z } from "zod";
+import type { DocsFrameworkConfig, DocsPage } from "./types";
+import {
+  DEFAULT_SEARCH_INDEX_OUTPUT_DIR,
+  type LocaleSearchIndexPayload,
+  type SearchIndexDocument,
+  type SearchIndexManifest,
+  type SearchIndexManifestEntry,
+} from "./search-index-types";
+import { markdownToSearchText } from "./markdown-search-text";
+const MANIFEST_FILENAME = "manifest.json";
+
+const pageFieldsSchema = z.object({
+  title: z.string().min(1),
+  body: z.string(),
+  category: z.string().min(1),
+  order: z.preprocess(
+    (value) => {
+      if (typeof value === "string") {
+        return Number(value);
+      }
+      return value;
+    },
+    z.number().finite(),
+  ),
+});
+
+export type GenerateStaticSearchIndexesOptions = {
+  config: DocsFrameworkConfig;
+  cwd?: string;
+  outputDir?: string;
+  logger?: (message: string) => void;
+};
+
+export type GenerateStaticSearchIndexesResult = {
+  outputDir: string;
+  manifestPath: string;
+  manifest: SearchIndexManifest;
+};
+
+type RuntimeLocales = {
+  defaultLocale: string;
+  locales: string[];
+};
+
+function normalizeLocales(locales: string[]): string[] {
+  const unique = new Set<string>();
+
+  for (const locale of locales) {
+    const normalized = locale.trim();
+    if (normalized) {
+      unique.add(normalized);
+    }
+  }
+
+  return [...unique];
+}
+
+function resolveConfiguredRuntimeLocales(config: DocsFrameworkConfig): RuntimeLocales {
+  const locales = normalizeLocales(config.routing.locales);
+  const fallbackDefault = config.routing.defaultLocale;
+  const hasDefault = locales.includes(fallbackDefault);
+  const defaultLocale = hasDefault ? fallbackDefault : (locales[0] ?? fallbackDefault);
+
+  return {
+    defaultLocale,
+    locales: locales.length > 0 ? locales : [fallbackDefault],
+  };
+}
+
+function sanitizeLocaleForFileName(locale: string): string {
+  const normalized = locale.trim().toLowerCase();
+  return normalized.replace(/[^a-z0-9-]/g, "-");
+}
+
+function normalizeSlugPart(value: string): string {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+
+function joinPath(...segments: string[]): string {
+  const clean = segments.map(normalizeSlugPart).filter(Boolean);
+  return `/${clean.join("/")}`;
+}
+
+function toDocsPagePath(config: DocsFrameworkConfig, locale: string, slug: string): string {
+  return joinPath(locale, config.routing.basePath, slug);
+}
+
+function normalizePage(item: ContentItem<Record<string, unknown>>): DocsPage {
+  const parsed = pageFieldsSchema.safeParse(item.data);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => issue.message).join("; ");
+    throw new Error(`Invalid page shape for slug "${item.slug}": ${issues}`);
+  }
+
+  return {
+    slug: item.slug,
+    title: parsed.data.title,
+    body: parsed.data.body,
+    category: parsed.data.category,
+    order: parsed.data.order,
+    locale: item.locale,
+  };
+}
+
+function sortPages(pages: DocsPage[]): DocsPage[] {
+  return [...pages].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+
+function buildDocument(page: DocsPage, config: DocsFrameworkConfig, locale: string): SearchIndexDocument {
+  return {
+    id: `${locale}:${page.slug}`,
+    locale,
+    slug: page.slug,
+    title: page.title,
+    path: toDocsPagePath(config, locale, page.slug),
+    order: page.order,
+    plainText: markdownToSearchText(page.body),
+  };
+}
+
+function toStableJson(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function buildIndexFileName(locale: string, payloadJson: string): {
+  fileName: string;
+  hash: string;
+} {
+  const hash = createHash("sha256").update(payloadJson).digest("hex").slice(0, 12);
+  const fileName = `index.${sanitizeLocaleForFileName(locale)}.${hash}.json`;
+  return { fileName, hash };
+}
+
+function createLocaleClient(config: DocsFrameworkConfig, locale?: string): SupatentClient {
+  return createClient({
+    baseUrl: config.supatent.baseUrl,
+    projectSlug: config.supatent.projectSlug,
+    apiKey: config.supatent.apiKey,
+    preview: false,
+    locale,
+    cache: config.supatent.cache,
+  });
+}
+
+async function fetchRuntimeLocales(config: DocsFrameworkConfig): Promise<RuntimeLocales> {
+  try {
+    const response = await createLocaleClient(config).getLocales();
+    const locales = normalizeLocales(response.locales.map((entry) => entry.code));
+
+    if (locales.length === 0) {
+      throw new Error("Supatent returned no locales.");
+    }
+
+    const defaultLocale = locales.includes(response.default)
+      ? response.default
+      : locales[0];
+
+    return {
+      defaultLocale,
+      locales,
+    };
+  } catch {
+    return resolveConfiguredRuntimeLocales(config);
+  }
+}
+
+async function fetchPublishedPagesForLocale(
+  config: DocsFrameworkConfig,
+  locale: string,
+): Promise<DocsPage[]> {
+  const items = await createLocaleClient(config, locale)
+    .schema<Record<string, unknown>>(config.schemas.page)
+    .all();
+
+  const published = items.filter((item) => item.publishedAt !== null);
+  return sortPages(published.map(normalizePage));
+}
+
+async function clearGeneratedIndexFiles(outputDir: string): Promise<void> {
+  const entries = await readdir(outputDir, { withFileTypes: true });
+  await Promise.all(
+    entries
+      .filter(
+        (entry) =>
+          entry.isFile() &&
+          (entry.name === MANIFEST_FILENAME ||
+            (entry.name.startsWith("index.") && entry.name.endsWith(".json"))),
+      )
+      .map((entry) => unlink(path.join(outputDir, entry.name))),
+  );
+}
+
+export function createLocaleSearchIndexPayload(
+  locale: string,
+  pages: DocsPage[],
+  config: DocsFrameworkConfig,
+  generatedAt: string,
+): LocaleSearchIndexPayload {
+  return {
+    locale,
+    generatedAt,
+    documents: pages.map((page) => buildDocument(page, config, locale)),
+  };
+}
+
+export async function generateStaticSearchIndexes(
+  options: GenerateStaticSearchIndexesOptions,
+): Promise<GenerateStaticSearchIndexesResult> {
+  const { config, logger } = options;
+  const cwd = options.cwd ?? process.cwd();
+  const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_SEARCH_INDEX_OUTPUT_DIR);
+
+  await mkdir(outputDir, { recursive: true });
+  await clearGeneratedIndexFiles(outputDir);
+
+  const runtimeLocales = await fetchRuntimeLocales(config);
+  const generatedAt = new Date().toISOString();
+  const manifestEntries: SearchIndexManifestEntry[] = [];
+
+  for (const locale of runtimeLocales.locales) {
+    const pages = await fetchPublishedPagesForLocale(config, locale);
+    const payload = createLocaleSearchIndexPayload(locale, pages, config, generatedAt);
+    const payloadJson = toStableJson(payload);
+    const { fileName, hash } = buildIndexFileName(locale, payloadJson);
+    await writeFile(path.join(outputDir, fileName), payloadJson, "utf8");
+
+    manifestEntries.push({
+      locale,
+      file: fileName,
+      hash,
+      documentCount: payload.documents.length,
+    });
+
+    logger?.(
+      `Built search index locale=${locale} docs=${payload.documents.length} file=${fileName}`,
+    );
+  }
+
+  const manifest: SearchIndexManifest = {
+    version: 1,
+    generatedAt,
+    defaultLocale: runtimeLocales.defaultLocale,
+    basePath: config.routing.basePath,
+    outputDir: options.outputDir ?? DEFAULT_SEARCH_INDEX_OUTPUT_DIR,
+    entries: manifestEntries,
+  };
+
+  const manifestPath = path.join(outputDir, MANIFEST_FILENAME);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  logger?.(`Wrote search index manifest: ${manifestPath}`);
+
+  return {
+    outputDir,
+    manifestPath,
+    manifest,
+  };
+}

package/runtime/src/framework/service.ts

@@ -0,0 +1,302 @@
+import type {
+  DocsCategory,
+  DocsDataMode,
+  DocsFrameworkConfig,
+  DocsLocaleRuntimeConfig,
+  DocsNavNode,
+  DocsPage,
+  DocsPageResolution,
+} from "./types";
+import { DocsFrameworkError } from "./errors";
+import type { DocsRepository } from "./repository";
+import { createSupatentDocsRepository } from "./repository";
+import { resolveLocaleCandidates } from "./locales";
+import { buildNavigationTree } from "./navigation";
+import {
+  toDocsAiAllPath,
+  toDocsAiIndexPath,
+  toDocsMarkdownPath,
+  toDocsPagePath,
+} from "./url";
+import { markdownToPlainText } from "./rendering";
+
+type DocsNavigationResult = {
+  requestedLocale: string;
+  resolvedLocale: string;
+  usedFallback: boolean;
+  navigation: DocsNavNode[];
+  pages: DocsPage[];
+  categories: DocsCategory[];
+};
+
+type DocsAiIndexResult = {
+  requestedLocale: string;
+  resolvedLocale: string;
+  usedFallback: boolean;
+  route: string;
+  pages: Array<{
+    slug: string;
+    title: string;
+    locale: string;
+    htmlPath: string;
+    markdownPath: string;
+  }>;
+};
+
+type DocsAiAllResult = {
+  requestedLocale: string;
+  resolvedLocale: string;
+  usedFallback: boolean;
+  route: string;
+  pages: Array<{
+    slug: string;
+    title: string;
+    locale: string;
+    markdown: string;
+    plainText: string;
+    htmlPath: string;
+    markdownPath: string;
+  }>;
+};
+
+type DocsServiceOptions = {
+  dataMode?: DocsDataMode;
+  localeConfig?: DocsLocaleRuntimeConfig;
+  repository?: DocsRepository;
+};
+
+export function createDocsService(
+  config: DocsFrameworkConfig,
+  options: DocsServiceOptions = {},
+) {
+  const dataMode = options.dataMode ?? config.supatent.dataMode;
+  const localeConfig = options.localeConfig ?? config.routing;
+  const repository =
+    options.repository ?? createSupatentDocsRepository(config, { dataMode });
+  const publishedOnly = dataMode === "published";
+
+  async function resolvePublishedPages(requestedLocale: string): Promise<{
+    requestedLocale: string;
+    resolvedLocale: string;
+    usedFallback: boolean;
+    pages: DocsPage[];
+    categories: DocsCategory[];
+  } | null>;
+  async function resolvePublishedPages(
+    requestedLocale: string,
+    options: { resolveMarkdownAssets?: boolean },
+  ): Promise<{
+    requestedLocale: string;
+    resolvedLocale: string;
+    usedFallback: boolean;
+    pages: DocsPage[];
+    categories: DocsCategory[];
+  } | null>;
+  async function resolvePublishedPages(
+    requestedLocale: string,
+    options: { resolveMarkdownAssets?: boolean } = {},
+  ): Promise<{
+    requestedLocale: string;
+    resolvedLocale: string;
+    usedFallback: boolean;
+    pages: DocsPage[];
+    categories: DocsCategory[];
+  } | null> {
+    function sortPagesWithinCategories(
+      pages: DocsPage[],
+      categories: DocsCategory[],
+    ): DocsPage[] {
+      const pagesByCategory = new Map<string, DocsPage[]>();
+      for (const page of pages) {
+        const list = pagesByCategory.get(page.category);
+        if (list) {
+          list.push(page);
+        } else {
+          pagesByCategory.set(page.category, [page]);
+        }
+      }
+
+      const orderedCategories = [...categories].sort((a, b) => {
+        if (a.order === b.order) {
+          return a.slug.localeCompare(b.slug);
+        }
+        return a.order - b.order;
+      });
+
+      const orderedPages: DocsPage[] = [];
+      for (const category of orderedCategories) {
+        const categoryPages = [...(pagesByCategory.get(category.slug) ?? [])].sort((a, b) => {
+          if (a.order === b.order) {
+            return a.slug.localeCompare(b.slug);
+          }
+          return a.order - b.order;
+        });
+        orderedPages.push(...categoryPages);
+      }
+
+      return orderedPages;
+    }
+
+    const candidates = resolveLocaleCandidates(requestedLocale, localeConfig);
+    for (const locale of candidates) {
+      const [pages, categories] = await Promise.all([
+        repository.getPages(locale, {
+          publishedOnly,
+          resolveMarkdownAssets: options.resolveMarkdownAssets,
+        }),
+        repository.getCategories(locale, { publishedOnly }),
+      ]);
+      if (pages.length > 0) {
+        if (categories.length === 0) {
+          throw new DocsFrameworkError(
+            "DATA_ERROR",
+            `No categories found for locale "${locale}" while pages exist.`,
+          );
+        }
+
+        const categorySlugSet = new Set(categories.map((entry) => entry.slug));
+        const missingCategories = pages
+          .filter((page) => !categorySlugSet.has(page.category))
+          .map((page) => `${page.slug} -> ${page.category}`);
+
+        if (missingCategories.length > 0) {
+          throw new DocsFrameworkError(
+            "DATA_ERROR",
+            `Pages reference missing categories for locale "${locale}": ${missingCategories.join(", ")}`,
+          );
+        }
+
+        return {
+          requestedLocale,
+          resolvedLocale: locale,
+          usedFallback: locale !== requestedLocale,
+          pages: sortPagesWithinCategories(pages, categories),
+          categories,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  async function getPageBySlug(
+    requestedLocale: string,
+    slug: string,
+    options: { resolveMarkdownAssets?: boolean } = {},
+  ): Promise<DocsPageResolution | null> {
+    const candidates = resolveLocaleCandidates(requestedLocale, localeConfig);
+    for (const locale of candidates) {
+      const page = await repository.getPageBySlugLocale(slug, locale, {
+        publishedOnly,
+        resolveMarkdownAssets: options.resolveMarkdownAssets,
+      });
+      if (page) {
+        return {
+          page,
+          requestedLocale,
+          resolvedLocale: locale,
+          usedFallback: locale !== requestedLocale,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  return {
+    async getPage(requestedLocale: string, slug = ""): Promise<DocsPageResolution | null> {
+      if (slug) {
+        return getPageBySlug(requestedLocale, slug, {
+          resolveMarkdownAssets: true,
+        });
+      }
+
+      const resolvedPages = await resolvePublishedPages(requestedLocale);
+      if (!resolvedPages || resolvedPages.pages.length === 0) {
+        return null;
+      }
+
+      const firstPage = await repository.getPageBySlugLocale(
+        resolvedPages.pages[0].slug,
+        resolvedPages.resolvedLocale,
+        {
+          publishedOnly,
+          resolveMarkdownAssets: true,
+        },
+      );
+      if (!firstPage) {
+        return null;
+      }
+
+      return {
+        page: firstPage,
+        requestedLocale,
+        resolvedLocale: resolvedPages.resolvedLocale,
+        usedFallback: resolvedPages.usedFallback,
+      };
+    },
+
+    async getNavigation(requestedLocale: string): Promise<DocsNavigationResult | null> {
+      const resolvedPages = await resolvePublishedPages(requestedLocale);
+      if (!resolvedPages) {
+        return null;
+      }
+
+      return {
+        ...resolvedPages,
+        navigation: buildNavigationTree(
+          resolvedPages.pages,
+          resolvedPages.categories,
+          requestedLocale,
+          config,
+        ),
+      };
+    },
+
+    async getAiIndex(requestedLocale: string): Promise<DocsAiIndexResult | null> {
+      const resolvedPages = await resolvePublishedPages(requestedLocale);
+      if (!resolvedPages) {
+        return null;
+      }
+
+      return {
+        requestedLocale,
+        resolvedLocale: resolvedPages.resolvedLocale,
+        usedFallback: resolvedPages.usedFallback,
+        route: toDocsAiIndexPath(config, requestedLocale),
+        pages: resolvedPages.pages.map((page) => ({
+          slug: page.slug,
+          title: page.title,
+          locale: page.locale,
+          htmlPath: toDocsPagePath(config, requestedLocale, page.slug),
+          markdownPath: toDocsMarkdownPath(config, requestedLocale, page.slug),
+        })),
+      };
+    },
+
+    async getAiAll(requestedLocale: string): Promise<DocsAiAllResult | null> {
+      const resolvedPages = await resolvePublishedPages(requestedLocale, {
+        resolveMarkdownAssets: true,
+      });
+      if (!resolvedPages) {
+        return null;
+      }
+
+      return {
+        requestedLocale,
+        resolvedLocale: resolvedPages.resolvedLocale,
+        usedFallback: resolvedPages.usedFallback,
+        route: toDocsAiAllPath(config, requestedLocale),
+        pages: resolvedPages.pages.map((page) => ({
+          slug: page.slug,
+          title: page.title,
+          locale: page.locale,
+          markdown: page.body,
+          plainText: markdownToPlainText(page.body),
+          htmlPath: toDocsPagePath(config, requestedLocale, page.slug),
+          markdownPath: toDocsMarkdownPath(config, requestedLocale, page.slug),
+        })),
+      };
+    },
+  };
+}