@stainless-api/docs 0.1.0-beta.99 → 1.0.0-beta.141

package/plugin/index.ts

@@ -1,9 +1,7 @@
 import react from '@astrojs/react';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
 import type { AstroIntegration } from 'astro';
-import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
-// import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
   makePlaceholderItems,
@@ -28,12 +26,17 @@ import { getSharedLogger } from '../shared/getSharedLogger';
 import { resolveSrcFile } from '../resolveSrcFile';
 import { mkdir, writeFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
-import prebundleWorkers from 'vite-plugin-prebundle-workers';
-import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import type * as VirtualManifestModule from 'virtual:stainless-apis-manifest';
+
+import {
+  generateMissingRouteList,
+  isSupportedLanguage,
+  type DocsLanguage,
+} from '@stainless-api/docs-ui/routing';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
+import { flatSpecsList, loadAllSpecs, LoadedSpecs } from './specs/utils';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -91,58 +94,24 @@ export function generateAPIReferenceItems(
   return makePlaceholderItems(id);
 }
 
-async function stlStarlightAstroIntegration(
-  pluginConfig: NormalizedStainlessStarlightConfig,
-): Promise<AstroIntegration> {
+function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlightConfig): AstroIntegration {
   const virtualId = `virtual:stl-starlight-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
-  let playgroundsBase: string | undefined;
-  let buildPlaygrounds;
   let astroBase = '/';
 
-  let specLoader: SpecLoader | undefined;
-  async function resolveSpecs() {
-    if (!specLoader) throw new Error('Expected spec loader to exist');
-    const result = await specLoader.specPromise;
-    return result.specComposite;
-  }
+  let specsPromise: Promise<LoadedSpecs> | undefined;
+  async function specsPromiseResolved() {
+    if (!specsPromise) throw new Error('Expected spec promise to exist');
+    const result = await specsPromise;
 
-  let building: Promise<void> | undefined;
-  let reportError: ((message: string) => void) | null = null;
-  let collectedErrors: string[] | null = null;
-
-  function startPlaygroundsBuild(playgroundsCachePath: string) {
-    if (!pluginConfig.experimentalPlaygrounds) return;
-    if (building) return building;
-    return (building = (async () => {
-      const specComposite = await resolveSpecs();
-
-      if (specComposite.listUniqueSpecs().length > 1) {
-        throw new Error('Multiple specs found. This is not supported for Playgrounds.');
-      }
-
-      const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
-      const auth = specComposite.listUniqueSpecs()[0]!.data.auth;
-
-      const langs = specComposite.getLanguages();
-
-      await buildPlaygrounds!({
-        spec,
-        langs,
-        auth,
-        playPath: playgroundsCachePath,
-        reportError(message: string) {
-          (reportError ?? console.error)(message);
-        },
-      });
-    })());
+    return result;
   }
 
   return {
     name: 'stl-starlight-astro',
     hooks: {
-      'astro:config:setup': async ({
+      'astro:config:setup': ({
         injectRoute,
         updateConfig,
         logger: localLogger,
@@ -154,18 +123,24 @@ async function stlStarlightAstroIntegration(
         const projectDir = astroConfig.root.pathname;
         astroBase = astroConfig.base;
 
-        specLoader = await startSpecLoader(pluginConfig, logger, createCodegenDir());
-
-        reportError = (message: string) => logger.error(message);
-
-        if (pluginConfig.experimentalPlaygrounds) {
-          playgroundsBase = pluginConfig.experimentalPlaygrounds.playgroundsBase;
-        }
+        specsPromise = loadAllSpecs(
+          pluginConfig.loadSpecs({
+            stainlessProject: pluginConfig.stainlessProject,
+            branch: pluginConfig.branch,
+            apiKey: pluginConfig.apiKey?.value ?? null,
+            excludeLanguages: pluginConfig.excludeLanguages,
+            logger,
+            createCodegenDir,
+          }),
+        );
 
-        const middlewareFile = path.join(projectDir, 'middleware.stainless.ts');
+        const middlewareFileBase = path.join(projectDir, 'middleware.stainless');
+        const middlewareFile = ['.tsx', '.ts']
+          .map((ext) => middlewareFileBase + ext)
+          .find((f) => fs.existsSync(f));
 
         let vmMiddlewareExport = 'export const MIDDLEWARE = {};';
-        if (fs.existsSync(middlewareFile)) {
+        if (middlewareFile) {
           logger.debug(`Loading middleware from ${middlewareFile}`);
           vmMiddlewareExport = `export { default as MIDDLEWARE } from '${middlewareFile}';`;
         }
@@ -176,6 +151,12 @@ async function stlStarlightAstroIntegration(
           prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
         });
 
+        injectRoute({
+          pattern: `${pluginConfig.basePath}/index.md`,
+          entrypoint: resolveSrcFile('/plugin/routes/markdown.ts'),
+          prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
+        });
+
         const astroFile = command === 'build' ? 'DocsStatic' : 'Docs';
         injectRoute({
           pattern: `${pluginConfig.basePath}/[...slug]`,
@@ -189,6 +170,16 @@ async function stlStarlightAstroIntegration(
           prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
         });
 
+        if (pluginConfig.llmsTxt.enabled) {
+          injectRoute({
+            pattern: '/llms.txt',
+            entrypoint: resolveSrcFile('/plugin/routes/llms.ts'),
+            prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
+          });
+        } else {
+          logger.info('LLMS.txt generation is disabled.');
+        }
+
         updateConfig({
           vite: {
             plugins: [
@@ -196,24 +187,28 @@ async function stlStarlightAstroIntegration(
                 'virtual:stl-starlight-reference-sidebars',
                 async () => {
                   // we know specLoader exists here
-                  const { specComposite } = await specLoader!.specPromise;
+                  const specs = await specsPromiseResolved();
 
                   const sidebars = [...sidebarConfigs.entries()]
                     // produce all { id, language } combos with the attached config
                     // flattens to one item per language * id combo
                     .flatMap(([id, config]) =>
-                      specComposite.listAllLanguagesAndIncludeSpecs().map((res) => ({
-                        id,
-                        config,
-                        language: res.language,
-                        spec: res.spec.data.sdkJson,
-                      })),
+                      flatSpecsList(specs)
+                        .filter((res): res is typeof res & { language: DocsLanguage } =>
+                          isSupportedLanguage(res.language),
+                        )
+                        .map((res) => ({
+                          id,
+                          config,
+                          language: res.language,
+                          sdkJson: res.sdkJson,
+                        })),
                     )
                     // produce a sidebar for each
                     // later we will .find() the sidebar that matches the (id, language)
-                    .map(({ id, config, language, spec }) => {
+                    .map(({ id, config, language, sdkJson }) => {
                       const configItemsBuilder = new SidebarConfigItemsBuilder(
-                        spec,
+                        sdkJson,
                         language,
                         config.options,
                       );
@@ -227,11 +222,11 @@ async function stlStarlightAstroIntegration(
                       return {
                         id,
                         language,
-                        // this has to run multpile times because it depends on the
+                        // this has to run multiple times because it depends on the
                         // userSidebarConfig (which is per-id) and the language
                         entries: toStarlightSidebar({
                           basePath: path.posix.join(astroBase, pluginConfig.basePath),
-                          spec,
+                          spec: sdkJson,
                           entries: userSidebarConfig,
                           currentLanguage: language,
                         }),
@@ -241,58 +236,33 @@ async function stlStarlightAstroIntegration(
                   return { sidebars };
                 },
               ),
-              ...specLoader.vitePlugins,
+              makeAsyncVirtualModPlugin<typeof VirtualManifestModule>(
+                'virtual:stainless-apis-manifest',
+                async () => {
+                  // this virtual module only resolves when the specs are loaded
+                  // this prevents the SSR module from trying to read the spec file before it's generated
+                  const specs = await specsPromiseResolved();
+
+                  return {
+                    api: {
+                      languages: specs
+                        .map((s) =>
+                          s.languages
+                            .filter(isSupportedLanguage)
+                            .map((lang) => ({ language: lang, sdkJSONFilePath: s.filePath })),
+                        )
+                        .flat(),
+                    },
+                  };
+                },
+              ),
               {
                 name: 'stl-starlight-vite',
-                buildStart() {
-                  building = undefined;
-                },
-                async configureServer(server) {
-                  if (playgroundsBase) {
-                    buildPlaygrounds = (await server.ssrLoadModule(playgroundsBase + '/src/build.ts'))
-                      .buildPlaygrounds;
-                  }
-
-                  // TODO: eventually - re-add support for watching local input changes (eg. reloading when OAS/config files change)
-                },
+                // TODO: eventually - re-add support for watching local input changes (eg. reloading when OAS/config files change)
                 resolveId(id) {
                   if (id === virtualId) {
                     return resolvedId;
                   }
-                  if (id === 'virtual:stl-playground/unstable-update-language') {
-                    return resolveSrcFile('plugin/languages.ts');
-                  }
-                  if (id === 'virtual:stl-playground/create') {
-                    return fileURLToPath(
-                      new URL(
-                        pluginConfig.experimentalPlaygrounds
-                          ? path.join(playgroundsBase!, '/src/create.tsx')
-                          : './globalJs/create-playground.shim.ts',
-                        import.meta.url,
-                      ),
-                    );
-                  }
-                  if (id === 'virtual:stl-playground/data') {
-                    return fileURLToPath(
-                      new URL(
-                        pluginConfig.experimentalPlaygrounds
-                          ? './globalJs/playground-data.ts'
-                          : './globalJs/playground-data.shim.ts',
-                        import.meta.url,
-                      ),
-                    );
-                  }
-                  if (id.startsWith('virtual:stl-playground/')) {
-                    const result = path.join(
-                      this.environment.getTopLevelConfig().cacheDir,
-                      'stl-playground',
-                      id.slice('virtual:stl-playground/'.length),
-                    );
-                    const config = this.environment.getTopLevelConfig();
-                    return startPlaygroundsBuild(path.join(config.cacheDir, 'stl-playground'))?.then(
-                      () => result,
-                    );
-                  }
                 },
                 load(id) {
                   if (id === resolvedId) {
@@ -309,62 +279,39 @@ async function stlStarlightAstroIntegration(
                         EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS:
                           pluginConfig.experimentalCollapsibleMethodDescriptions,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
-                        ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
-                        EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
+                        ENABLE_CONTEXT_MENU: !!pluginConfig.contextMenu,
+                        CONTEXT_MENU_ENABLE_THIRD_PARTY:
+                          (typeof pluginConfig.contextMenu === 'object'
+                            ? pluginConfig.contextMenu.thirdParty
+                            : null) ?? true,
                         EXPERIMENTAL_REQUEST_BUILDER: pluginConfig.experimentalRequestBuilder,
                         STAINLESS_PROJECT: pluginConfig.stainlessProject,
+                        LLMS_TXT_DESCRIPTION: pluginConfig.llmsTxt.description,
+                        LLMS_TXT_DETAIL_THRESHOLD: pluginConfig.llmsTxt.detailThreshold,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
                   }
                 },
               },
-              prebundleWorkers({
-                include: [
-                  '**/typescript/runner*',
-                  '**/typescript/worker*',
-                  '**/pyright.worker*',
-                  '**/python/pyodide*',
-                ],
-                configureEsBuild(_, opts) {
-                  opts.external ??= [];
-                  opts.external.push('url');
-                  opts.loader ??= {};
-                  opts.loader['.wasm'] = 'dataurl';
-                  return opts;
-                },
-              }),
             ],
           },
         });
       },
-      'astro:build:start'({ logger }) {
-        collectedErrors = [];
-        reportError = (message: string) => {
-          logger.error(message);
-          collectedErrors!.push(message);
-        };
-      },
       'astro:build:done': async ({ dir, logger }) => {
         const dist = fileURLToPath(dir);
         const stainlessDir = path.join(dist, '_stainless');
         await mkdir(stainlessDir, { recursive: true });
-        if (collectedErrors) {
-          for (const error of collectedErrors) {
-            logger.error(error);
-          }
-          collectedErrors = null;
-        }
 
         const manifest = {
           astroBase,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
-        const specComposite = await resolveSpecs();
+        const loadedSpecs = await specsPromiseResolved();
 
         await buildAlgoliaIndex({
-          specComposite,
+          loadedSpecs,
           logger,
         });
 
@@ -375,7 +322,7 @@ async function stlStarlightAstroIntegration(
         // about the missing method and provide links to SDKs where it is available.
 
         // TODO: (multi-spec) support multiple specs
-        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+        const spec = loadedSpecs[0]!.sdkJson;
 
         const missingRoutes = generateMissingRouteList({
           spec,
@@ -395,7 +342,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
   return {
     name: 'stl-starlight',
     hooks: {
-      'config:setup': async ({
+      'config:setup': ({
         addIntegration,
         updateConfig,
         addRouteMiddleware,
@@ -430,18 +377,17 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
-        // TODO: (multi-spec) re-add this? not strictly necessary to merge
-        // if ('apiKey' in config.specInputs) {
-        //   if (!config.specInputs.apiKey) {
-        //     logger.info(`Stainless credentials not loaded`);
-        //   } else if (config.specInputs.apiKey.source === 'explicit-config') {
-        //     logger.info(`Stainless credentials loaded from user config`);
-        //   } else if (config.specInputs.apiKey.source === 'environment-variable') {
-        //     logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
-        //   } else if (config.specInputs.apiKey.source === 'cli') {
-        //     logger.info('Stainless credentials loaded from `stl` CLI');
-        //   }
-        // })
+        if ('apiKey' in config) {
+          if (!config.apiKey) {
+            logger.info(`Stainless credentials not loaded`);
+          } else if (config.apiKey.source === 'explicit-config') {
+            logger.info(`Stainless credentials loaded from user config`);
+          } else if (config.apiKey.source === 'environment-variable') {
+            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+          } else if (config.apiKey.source === 'cli') {
+            logger.info('Stainless credentials loaded from `stl` CLI');
+          }
+        }
 
         if (starlightConfig.sidebar) {
           // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
@@ -455,14 +401,14 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
         }
 
-        addIntegration(await stlStarlightAstroIntegration(config));
+        addIntegration(stlStarlightAstroIntegration(config));
 
         const expressiveCodeConfig =
           typeof starlightConfig.expressiveCode === 'object' ? starlightConfig.expressiveCode : {};
 
         const themes = expressiveCodeConfig.themes
-          ? (expressiveCodeConfig.themes as BundledTheme[])
-          : (['github-light', 'github-dark'] as BundledTheme[]);
+          ? expressiveCodeConfig.themes
+          : (['github-light', 'github-dark'] satisfies (typeof expressiveCodeConfig)['themes']);
 
         updateConfig({
           sidebar: starlightConfig.sidebar,
@@ -486,5 +432,3 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 // Additional exports we want for Stainless <-> docs integration.
 export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
 export { renderMarkdown } from '@stainless-api/docs-ui/markdown';
-
-export { resolveSpec } from './specs/inputResolver';