npm - radiant-docs - Versions diffs - 0.1.66 → 0.1.68 - Mend

radiant-docs 0.1.66 → 0.1.68

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/package.json +1 -1
package/template/astro.config.mjs +24 -2
package/template/package-lock.json +8 -8
package/template/package.json +2 -2
package/template/src/components/MdxPage.astro +12 -2
package/template/src/components/OpenApiPage.astro +13 -3
package/template/src/components/PageAiActions.astro +715 -0
package/template/src/components/endpoint/PlaygroundButton.astro +1 -1
package/template/src/components/endpoint/PlaygroundForm.astro +8 -0
package/template/src/layouts/Layout.astro +6 -1
package/template/src/lib/ai-artifacts.ts +295 -13
package/template/src/pages/{[...slug]/index.md.ts → [...slug].md.ts} +1 -1

package/template/src/components/endpoint/PlaygroundButton.astro CHANGED Viewed

@@ -65,7 +65,7 @@ import { Icon } from "astro-icon/components";
       x-on:pointerdown="onOverlayPointerDown($event)"
       x-on:pointerup="onOverlayPointerUp($event)"
       x-on:pointercancel="backdropInteractionStarted = false"
-      class="relative z-50 flex min-h-screen items-center justify-center p-2 xs:p-4 md:p-8"
+      class="relative z-50 flex h-dvh items-center justify-center p-2 xs:p-4 md:p-8"
     >
       <div
         x-on:click.stop

package/template/src/components/endpoint/PlaygroundForm.astro CHANGED Viewed

@@ -1062,6 +1062,14 @@ const headerValuePrefixes = Object.fromEntries(
   </div>
 </div>
+<style is:global>
+  @media (max-width: 639px) {
+    [data-playground-form-root] :is(input, select, textarea) {
+      font-size: 16px;
+    }
+  }
+</style>
 <script>
   import {
     highlightAssistantCodeToHtml,

package/template/src/layouts/Layout.astro CHANGED Viewed

@@ -75,6 +75,8 @@ const navigationTabs = config.navigation.tabs as
 const hasNavigationTabs =
   Array.isArray(navigationTabs?.items) && navigationTabs.items.length > 0;
 const tabsPresentation = navigationTabs?.presentation ?? "topbar";
+const hasTopbarNavigationTabs =
+  hasNavigationTabs && tabsPresentation === "topbar";
 ---
 <!doctype html>
@@ -356,7 +358,10 @@ const tabsPresentation = navigationTabs?.presentation ?? "topbar";
     <!-- Main Content -->
     <div
-      class="mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-background"
+      class:list={[
+        "mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-background",
+        hasTopbarNavigationTabs && "lg:pt-[108px]",
+      ]}
     >
       <main class="mx-auto pt-16 pb-20 min-h-[calc(100vh-64px)]">
         <slot />

package/template/src/lib/ai-artifacts.ts CHANGED Viewed

@@ -9,6 +9,7 @@ import {
   type MdxRoute,
   type OpenApiRoute,
 } from "./routes";
+import { parseOpenApiEndpoint } from "./utils";
 import {
   getOpenApiOperationDoc,
   OPENAPI_REQUEST_SECTION_LABELS,
@@ -18,10 +19,19 @@ import {
   type OpenApiRequestSectionVariantData,
 } from "./openapi/operation-doc";
 import { resolvePageDescription } from "./page-description";
-import { getConfig } from "./validation";
+import {
+  getConfig,
+  type DocsConfig,
+  type NavGroup,
+  type NavMenu,
+  type NavOpenApi,
+  type NavOpenApiPage,
+  type NavPage,
+} from "./validation";
 const DOCS_ROOT = path.join(process.cwd(), "src/content/docs");
 const MAX_DESCRIPTION_LENGTH = 300;
+const PRO_TIER = 3;
 const OPENAPI_SPEC_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
@@ -29,6 +39,7 @@ export const MARKDOWN_CONTENT_TYPE = "text/markdown; charset=utf-8";
 export const PLAIN_TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
 export type AiMarkdownPage = {
+  routeIdentity?: string;
   filePath: string;
   routeSlug?: string;
   title: string;
@@ -90,6 +101,24 @@ function buildPublicUrl(pathname: string): string {
   return new URL(publicPath, siteOrigin).toString();
 }
+function getOrgTier(): number {
+  const parsed = Number.parseInt((process.env.ORG_TIER ?? "1").trim(), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+}
+function formatMcpSection(): string[] {
+  if (getOrgTier() < PRO_TIER) return [];
+  return [
+    "## MCP",
+    "",
+    "This documentation exposes a read-only MCP server for AI agents:",
+    "",
+    `- MCP server: ${buildPublicUrl("/_mcp/server")}`,
+    "- Tool: searchDocs(query)",
+  ];
+}
 function getMarkdownPathForSlug(routeSlug: string): string {
   const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
   return normalizedSlug ? `/${normalizedSlug}.md` : "/index.md";
@@ -142,19 +171,23 @@ async function getMdxEntryByFilePath(filePath: string) {
 async function createMarkdownPage(args: {
   filePath: string;
   routeSlug?: string;
+  routeIdentity?: string;
   title?: string;
   markdownPath?: string;
   canonicalPath?: string;
 }): Promise<AiMarkdownPage> {
   const entry = await getMdxEntryByFilePath(args.filePath);
   if (!entry) {
-    throw new Error(`Could not find content collection entry for "${args.filePath}".`);
+    throw new Error(
+      `Could not find content collection entry for "${args.filePath}".`,
+    );
   }
   const { sourcePath, source } = await readMdxSource(args.filePath);
   const routeSlug = args.routeSlug ?? "";
   const markdownPath = args.markdownPath ?? getMarkdownPathForSlug(routeSlug);
-  const canonicalPath = args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
+  const canonicalPath =
+    args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
   const title =
     args.title ??
     resolveMdxPageTitle({
@@ -164,6 +197,7 @@ async function createMarkdownPage(args: {
   const config = await getConfig();
   return {
+    routeIdentity: args.routeIdentity,
     filePath: normalizeDocsRootRelativePath(args.filePath),
     routeSlug,
     title,
@@ -205,6 +239,7 @@ export async function getLlmsListedMarkdownPages(): Promise<AiMarkdownPage[]> {
       await createMarkdownPage({
         filePath: config.home,
         routeSlug: "",
+        routeIdentity: homeRoute?.routeIdentity,
         title: homeRoute?.title,
         markdownPath: "/index.md",
         canonicalPath: "/",
@@ -277,6 +312,234 @@ function formatDocsListItem(page: AiMarkdownPage): string {
   return `- [${page.title}](${page.markdownUrl})${description}`;
 }
+type LlmsTxtSection = {
+  title: string;
+  pages: AiMarkdownPage[];
+};
+type LlmsNavPageItem = string | NavPage | NavGroup | NavOpenApiPage;
+type LlmsNavigationContainer = {
+  pages?: LlmsNavPageItem[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
+function getAiMarkdownPageKey(page: AiMarkdownPage): string {
+  return page.routeIdentity ?? `${page.filePath}:${page.markdownUrl}`;
+}
+function buildLlmsSectionTitle(parts: string[]): string {
+  const title = parts
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join(": ");
+  return title || "Docs";
+}
+function isNavPageItem(item: LlmsNavPageItem): item is string | NavPage {
+  return typeof item === "string" || "page" in item;
+}
+function isNavGroupItem(item: LlmsNavPageItem): item is NavGroup {
+  return typeof item !== "string" && "group" in item;
+}
+function isNavOpenApiPageItem(
+  item: LlmsNavPageItem,
+): item is NavOpenApiPage {
+  return typeof item !== "string" && "openapi" in item;
+}
+function getNavPageRouteIdentity(item: string | NavPage): string {
+  return `mdx:${typeof item === "string" ? item : item.page}`;
+}
+function getNavOpenApiPageRouteIdentity(item: NavOpenApiPage): string | null {
+  const parsedEndpoint = parseOpenApiEndpoint(item.openapi.endpoint);
+  if (!parsedEndpoint) return null;
+  return `openapi:${item.openapi.source}:${parsedEndpoint.method} ${parsedEndpoint.path}`;
+}
+function getNavOpenApiSource(openapi: string | NavOpenApi): string {
+  return typeof openapi === "string" ? openapi : openapi.source;
+}
+function getOpenApiEndpointKey(method: string, pathStr: string): string {
+  return `${method.toUpperCase()} ${pathStr.toLowerCase()}`;
+}
+function matchesOpenApiEndpointFilter(
+  route: OpenApiRoute,
+  endpoints: string[],
+): boolean {
+  const routeEndpointKey = getOpenApiEndpointKey(
+    route.openApiMethod,
+    route.openApiPath,
+  );
+  return endpoints.some((endpoint) => {
+    const parsedEndpoint = parseOpenApiEndpoint(endpoint);
+    if (!parsedEndpoint) return false;
+    return (
+      getOpenApiEndpointKey(parsedEndpoint.method, parsedEndpoint.path) ===
+      routeEndpointKey
+    );
+  });
+}
+function getOpenApiFileRouteIdentities(
+  openapi: string | NavOpenApi,
+  routes: Route[],
+): string[] {
+  const source = getNavOpenApiSource(openapi);
+  const include = typeof openapi === "string" ? undefined : openapi.include;
+  const exclude = typeof openapi === "string" ? undefined : openapi.exclude;
+  return routes
+    .filter((route): route is OpenApiRoute => {
+      if (route.type !== "openapi" || route.filePath !== source) return false;
+      if (include && !matchesOpenApiEndpointFilter(route, include)) {
+        return false;
+      }
+      if (exclude && matchesOpenApiEndpointFilter(route, exclude)) {
+        return false;
+      }
+      return true;
+    })
+    .map((route) => route.routeIdentity);
+}
+function buildLlmsTxtSections(args: {
+  config: DocsConfig;
+  pages: AiMarkdownPage[];
+  routes: Route[];
+}): LlmsTxtSection[] {
+  const pageByRouteIdentity = new Map(
+    args.pages
+      .filter((page) => page.routeIdentity)
+      .map((page) => [page.routeIdentity as string, page]),
+  );
+  const emittedPageKeys = new Set<string>();
+  const sections: LlmsTxtSection[] = [];
+  const appendSection = (titleParts: string[], routeIdentities: string[]) => {
+    const sectionPages: AiMarkdownPage[] = [];
+    for (const routeIdentity of routeIdentities) {
+      const page = pageByRouteIdentity.get(routeIdentity);
+      if (!page) continue;
+      const pageKey = getAiMarkdownPageKey(page);
+      if (emittedPageKeys.has(pageKey)) continue;
+      emittedPageKeys.add(pageKey);
+      sectionPages.push(page);
+    }
+    if (sectionPages.length === 0) return;
+    const title = buildLlmsSectionTitle(titleParts);
+    const existingSection = sections.find((section) => section.title === title);
+    if (existingSection) {
+      existingSection.pages.push(...sectionPages);
+      return;
+    }
+    sections.push({
+      title,
+      pages: sectionPages,
+    });
+  };
+  const collectPages = (items: LlmsNavPageItem[], titleParts: string[]) => {
+    let directRouteIdentities: string[] = [];
+    const flushDirectPages = () => {
+      appendSection(titleParts, directRouteIdentities);
+      directRouteIdentities = [];
+    };
+    for (const item of items) {
+      if (isNavPageItem(item)) {
+        directRouteIdentities.push(getNavPageRouteIdentity(item));
+        continue;
+      }
+      if (isNavOpenApiPageItem(item)) {
+        const routeIdentity = getNavOpenApiPageRouteIdentity(item);
+        if (routeIdentity) directRouteIdentities.push(routeIdentity);
+        continue;
+      }
+      if (isNavGroupItem(item)) {
+        flushDirectPages();
+        collectNavigationContainer(
+          { pages: item.pages },
+          [...titleParts, item.group],
+        );
+      }
+    }
+    flushDirectPages();
+  };
+  const collectNavigationContainer = (
+    container: LlmsNavigationContainer,
+    titleParts: string[],
+  ) => {
+    if (container.pages) {
+      collectPages(container.pages, titleParts);
+    }
+    if (container.openapi) {
+      appendSection(
+        titleParts.length ? titleParts : ["API Reference"],
+        getOpenApiFileRouteIdentities(container.openapi, args.routes),
+      );
+    }
+    if (container.menu) {
+      for (const menuItem of container.menu.items) {
+        collectNavigationContainer(menuItem, [...titleParts, menuItem.label]);
+      }
+    }
+  };
+  const navigation = args.config.navigation;
+  if (navigation.pages) {
+    collectPages(navigation.pages, []);
+  } else if (navigation.menu) {
+    collectNavigationContainer({ menu: navigation.menu }, []);
+  } else if (navigation.openapi) {
+    collectNavigationContainer({ openapi: navigation.openapi }, [
+      "API Reference",
+    ]);
+  } else if (navigation.tabs) {
+    for (const tabItem of navigation.tabs.items) {
+      collectNavigationContainer(tabItem, [tabItem.label]);
+    }
+  }
+  const remainingPages = args.pages.filter(
+    (page) => !emittedPageKeys.has(getAiMarkdownPageKey(page)),
+  );
+  if (remainingPages.length > 0) {
+    sections.push({
+      title: sections.length ? "Additional Docs" : "Docs",
+      pages: remainingPages,
+    });
+  }
+  return sections;
+}
 function normalizeLocalOpenApiSource(source: string): string {
   return normalizeDocsRootRelativePath(source);
 }
@@ -297,7 +560,9 @@ function getOpenApiSpecLabel(source: string): string {
   if (isRemoteUrl(source)) {
     try {
       const url = new URL(source);
-      return path.posix.basename(url.pathname).replace(/\.[^.]+$/, "") || source;
+      return (
+        path.posix.basename(url.pathname).replace(/\.[^.]+$/, "") || source
+      );
     } catch {
       return source;
     }
@@ -344,7 +609,9 @@ function createOpenApiSpecArtifact(source: string): OpenApiSpecArtifact | null {
   };
 }
-export async function getOpenApiSpecArtifacts(): Promise<OpenApiSpecArtifact[]> {
+export async function getOpenApiSpecArtifacts(): Promise<
+  OpenApiSpecArtifact[]
+> {
   const routes = await getAllRoutes();
   const sources = new Set(
     routes
@@ -566,10 +833,7 @@ function getResponseContentTypes(response: any): string[] {
   return Object.keys(content);
 }
-function appendOpenApiResponsesMarkdown(
-  lines: string[],
-  responses: unknown,
-) {
+function appendOpenApiResponsesMarkdown(lines: string[], responses: unknown) {
   if (!responses || typeof responses !== "object") return;
   const responseEntries = Object.entries(responses).filter(
@@ -662,6 +926,7 @@ async function createOpenApiMarkdownPage(args: {
     args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
   return {
+    routeIdentity: args.route.routeIdentity,
     filePath: normalizeDocsRootRelativePath(args.route.filePath),
     routeSlug,
     title: args.route.title,
@@ -690,6 +955,7 @@ async function createRouteMarkdownPage(
     return createMarkdownPage({
       filePath: route.filePath,
       routeSlug: route.slug,
+      routeIdentity: route.routeIdentity,
       title: route.title,
       ...overrides,
     });
@@ -729,16 +995,30 @@ export async function getLlmsTxt(): Promise<string> {
   const config = await getConfig();
   const pages = await getLlmsListedMarkdownPages();
+  const routes = await getAllRoutes();
   const specs = await getOpenApiSpecArtifacts();
-  const lines = [`# ${config.title}`, "", "## Docs", ""];
-  lines.push(...pages.map(formatDocsListItem));
+  const sections = buildLlmsTxtSections({ config, pages, routes });
+  const lines = [`# ${config.title}`];
+  for (const section of sections) {
+    lines.push(
+      "",
+      `## ${section.title}`,
+      "",
+      ...section.pages.map(formatDocsListItem),
+    );
+  }
   const specsSection = formatOpenApiSpecsSection(specs);
   if (specsSection.length > 0) {
     lines.push("", ...specsSection);
   }
+  const mcpSection = formatMcpSection();
+  if (mcpSection.length > 0) {
+    lines.push("", ...mcpSection);
+  }
   return `${lines.join("\n").trimEnd()}\n`;
 }
@@ -785,7 +1065,9 @@ export async function getLlmsFullTxt(): Promise<string> {
       continue;
     }
-    sections.push(formatLlmsFullSpec(spec, await readOpenApiSpecArtifact(spec)));
+    sections.push(
+      formatLlmsFullSpec(spec, await readOpenApiSpecArtifact(spec)),
+    );
   }
   return `${sections.join("\n\n---\n\n").trimEnd()}\n`;

package/template/src/pages/{[...slug]/index.md.ts → [...slug].md.ts} RENAMED Viewed

@@ -3,7 +3,7 @@ import {
   getMarkdownRoutePages,
   MARKDOWN_CONTENT_TYPE,
   type AiMarkdownPage,
-} from "../../lib/ai-artifacts";
+} from "../lib/ai-artifacts";
 export async function getStaticPaths() {
   const pages = await getMarkdownRoutePages();